CLI

Agent Workflows

JSON-first and schema-driven workflows for agents, scripts, and automation

Overview

Better-T-Stack now supports a fully JSON-first workflow for agents and automation:

  • Raw JSON project creation with create-json
  • Raw JSON addon installation with add-json
  • Runtime schema introspection with schema
  • Local stdio MCP server with mcp
  • Structured addon configuration with addonOptions
  • Structured database setup configuration with dbSetupOptions
  • Safe planning with --dry-run

If you are automating the CLI from an LLM, CI job, or another tool, start here instead of the interactive prompt flow.

create-json

Create a project from a single JSON payload instead of many flags.

create-better-t-stack create-json --json '{
  "projectName": "my-app",
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "runtime": "bun",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "none",
  "addons": ["wxt", "mcp"],
  "addonOptions": {
    "wxt": { "template": "react", "devPort": 5555 },
    "mcp": {
      "scope": "project",
      "servers": ["context7"],
      "agents": ["cursor"]
    }
  },
  "install": false
}'

This is the best path when:

  • Your input already exists as structured data
  • You want to avoid shell flag expansion issues
  • You need nested addon or database setup options

add-json

Add addons to an existing project with a single JSON payload.

create-better-t-stack add-json --json '{
  "projectDir": "./my-app",
  "addons": ["skills", "ultracite"],
  "addonOptions": {
    "skills": {
      "scope": "project",
      "agents": ["cursor", "codex"],
      "selections": [
        {
          "source": "vercel-labs/agent-skills",
          "skills": ["web-design-guidelines"]
        },
        {
          "source": "https://www.evlog.dev",
          "skills": ["review-logging-patterns", "analyze-logs"]
        }
      ]
    },
    "ultracite": {
      "linter": "biome",
      "editors": ["vscode", "cursor"],
      "agents": ["claude", "codex"]
    }
  },
  "dryRun": true
}'

Runtime Schema Introspection

Use the CLI itself as the source of truth for current input shapes.

create-better-t-stack schema --name all
create-better-t-stack schema --name cli
create-better-t-stack schema --name createInput
create-better-t-stack schema --name addInput
create-better-t-stack schema --name addonOptions
create-better-t-stack schema --name dbSetupOptions

Useful patterns:

  • schema --name cli: inspect available commands
  • schema --name createInput: inspect the full create payload
  • schema --name addonOptions: inspect nested addon configuration
  • schema --name dbSetupOptions: inspect structured database setup behavior

mcp

Run Better-T-Stack itself as a local MCP server over stdio:

npx create-better-t-stack@latest mcp

Install it into supported agent configs with add-mcp:

npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"

Exposed tools:

  • bts_get_stack_guidance
  • bts_get_schema
  • bts_plan_project
  • bts_create_project
  • bts_plan_addons
  • bts_add_addons

This is the best path when an MCP-capable client should scaffold or modify Better-T-Stack projects without shelling out to a prompt-driven CLI flow.

Recommended MCP workflow:

  1. Call bts_get_stack_guidance if the user's request is ambiguous.
  2. Call bts_get_schema for the exact input shape you need.
  3. Build a full explicit stack config.
  4. Call bts_plan_project before bts_create_project.
  5. For MCP execution, use install: false when creating projects.
  6. Call bts_plan_addons before bts_add_addons.

For project creation, the MCP tools now expect a full explicit config, not a partial payload. That means the agent should provide all major stack choices such as:

  • frontend
  • backend
  • runtime
  • database
  • orm
  • api
  • auth
  • payments
  • addons
  • examples
  • dbSetup
  • webDeploy
  • serverDeploy
  • git
  • packageManager
  • install

Important field rules:

  • frontend means app surfaces, not styling choices.
  • addons must be an explicit array. Use [] when none are requested.
  • examples must be an explicit array. Use [] when none are requested.
  • dbSetup, webDeploy, and serverDeploy should be explicit even when the answer is none.
  • git, install, and packageManager should always be set explicitly.
  • install should usually be false for bts_create_project, because dependency installation can exceed common MCP client timeouts. Run npm install, pnpm install, or bun install separately after scaffolding.
  • If a request is still ambiguous after reading the guidance, the agent should resolve that ambiguity before calling bts_plan_project.

If you scaffold a project with the mcp addon, Better-T-Stack itself is now one of the recommended MCP servers. The addon installs it through add-mcp with a package runner command so the generated config does not rely on a globally installed CLI:

npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"

For Bun projects, the generated config uses the equivalent bunx create-better-t-stack@latest mcp server command inside add-mcp. That means MCP-capable agents inside the generated project can talk back to Better-T-Stack without any extra global install, alongside other recommended docs, framework, and database MCP servers.

Hosted MCP

For clients that can't run a local server, such as claude.ai, ChatGPT, and other web or mobile apps, Better-T-Stack also runs a hosted MCP server:

https://www.better-t-stack.dev/mcp

It uses Streamable HTTP and needs no API key. Add it as a remote or custom connector in your client.

The hosted server validates stacks and previews generated files, but it can't write to your machine. It returns the command to run instead:

  • bts_get_stack_guidance
  • bts_get_schema
  • bts_plan_project: validates a full explicit config and lists the files it generates
  • bts_preview_file: returns the contents of one generated file
  • bts_get_create_command: returns the create-better-t-stack command and a Stack Builder link

It validates with the same compatibility rules as the Stack Builder. An incompatible stack is rejected with the nearest valid values rather than silently changed. addonOptions and dbSetupOptions aren't accepted, because their rules are enforced by the CLI. Use create-json or the local server when you need them.

To create files directly or to add addons to an existing project, use the local mcp server above.

Use it inside your AI agent

Install the Better-T-Stack plugin and your assistant will scaffold and extend projects for you — just ask in plain English, like "create a fullstack app with Next, Hono, Postgres and Better Auth", and it builds a valid stack instead of hand-writing boilerplate.

Claude Code

Add the marketplace and install the plugin:

/plugin marketplace add AmanVarshney01/create-better-t-stack
/plugin install better-t-stack@better-t-stack

Then ask for a project in chat, or use the shortcuts:

  • /better-t-stack:new <description> — scaffold a new project
  • /better-t-stack:add <addons> — add addons to an existing one

Codex

Add the same marketplace from the Codex plugins screen and install Better-T-Stack, then ask for a project in chat.

Prefer just the tools without the plugin? Wire the MCP server into Codex with add-mcp:

npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"   # choose "codex"

Or add it to ~/.codex/config.toml directly:

[mcp_servers.better-t-stack]
command = "npx"
args = ["-y", "create-better-t-stack@latest", "mcp"]

opencode

Add the MCP server, then ask for a project in chat:

npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"   # choose "opencode"

Other agents

Any other agent works too, because Better-T-Stack is a CLI underneath:

  • MCP-capable agents (Cursor, VS Code, Gemini CLI, Zed, and more) — wire the server with npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp" and pick your agent.
  • CLI-first agents like pi — just ask it to scaffold with Better-T-Stack and it runs the create-better-t-stack CLI directly.

Structured Addon Options

Prompt-driven addons can be configured up front through addonOptions.

Supported structured addon surfaces include:

  • wxt
  • fumadocs
  • opentui
  • mcp
  • skills
  • ultracite

When skills is used with the evlog or axiom addon, Better-T-Stack recommends Evlog's agent skills from https://www.evlog.dev: review-logging-patterns and analyze-logs.

Example:

{
  "addons": ["wxt"],
  "addonOptions": {
    "wxt": {
      "template": "react",
      "devPort": 5555
    }
  }
}

Structured addon options are still persisted in bts.jsonc, but the printed reproducible command now stays on normal CLI flags for consistency. That means deeply nested addon or provider-specific setup options are not fully encoded in the one-line replay command.

Structured Database Setup Options

dbSetupOptions controls how database provisioning behaves in automation.

The supported modes are:

  • alchemy: provision the selected provider through Alchemy
  • auto: use the provider's automatic setup flow
  • manual: use an existing database and configure its credentials yourself

Example:

create-better-t-stack create-json --json '{
  "projectName": "db-app",
  "database": "postgres",
  "orm": "drizzle",
  "backend": "hono",
  "runtime": "bun",
  "api": "trpc",
  "frontend": ["tanstack-router"],
  "dbSetup": "neon",
  "dbSetupOptions": {
    "mode": "manual"
  }
}'

Current behavior:

  • When the database-consuming application deploys through Alchemy and the selected setup is Neon, PlanetScale, or Prisma Postgres, provisioning defaults to alchemy.

  • Otherwise, providers with automatic cloud provisioning default to manual in silent/agent flows:

    • turso
    • neon
    • prisma-postgres
    • supabase
    • mongodb-atlas
  • Providers that only write local/manual config today are not forced to manual:

    • d1
    • docker
    • planetscale

This keeps agents from accidentally creating cloud resources unless automation explicitly opts into auto, while leaving local or manual-only setups unchanged.

Provider-specific options are intentionally small today:

  • neon.method, neon.projectName, neon.regionId
  • prismaPostgres.regionId
  • turso.databaseName, turso.groupName, turso.installCli

Dry Runs

Use --dry-run to validate inputs and target directories without writing files.

create-better-t-stack --yes --dry-run
create-better-t-stack create-json --json '{"projectName":"my-app","yes":true,"dryRun":true}'
create-better-t-stack add-json --json '{"projectDir":"./my-app","addons":["mcp"],"dryRun":true}'

This is especially useful for:

  • Planning actions before mutation
  • CI validation
  • Agent reasoning loops

Programmatic API

The exported create() and add() APIs run in silent mode by default, so they benefit from the same agent-safe behavior as the JSON commands.

See Programmatic API for TypeScript examples.

Stored in bts.jsonc

Better-T-Stack persists structured configuration in bts.jsonc, including:

  • reproducibleCommand
  • addonOptions
  • dbSetupOptions

See bts.jsonc for the file format.

On this page