create-agent

CLI for scaffolding new Cloudflare Workers AI agents from templates.

Quick start

npm create @economic/agent@latest
# or
npx @economic/create-agent@latest

You'll be asked to:

1. Enter a project name
2. Choose where to create the project
3. Select a template
4. Fill in required variables (API keys, account IDs, etc.)
5. Optionally set up Gemini Enterprise Agent Platform ADC with gcloud (browser logins)

When done, your project is ready in the destination directory with dependencies installed and the local database migrated.

Non-interactive mode

Pass values via flags to skip prompts — useful for CI or scripting:

npx @economic/create-agent my-bot \
  --template chat \
  --dest ~/projects \
  --var ACCOUNT_ID=abc123 \
  --var AI_GATEWAY_ID=my-gateway \
  --var CF_AIG_TOKEN=tok-...

Secret inputs (API keys, tokens) are never persisted to the state file — pass them via --var on every run or enter them interactively.

Resuming a failed scaffold

If a step fails, fix the issue and resume from where it left off by passing the full project path:

npx @economic/create-agent --dest ~/projects/my-bot

To re-run a specific step:

npx @economic/create-agent --dest ~/projects/my-bot --step gemini-adc-auth
npx @economic/create-agent --dest ~/projects/my-bot --step create-resources

All flags

| Flag | Description | | ------------------- | -------------------------------------------------- | | [name] | Project name (lowercase letters, numbers, dashes) | | --dest <path> | Parent directory for the new project | | --template <name> | Skip template selector, use this template directly | | --step <name> | Re-run a single step | | --var KEY=VALUE | Pre-fill a user input (can be repeated) | | --list-templates | Print available templates and exit | | --help | Show usage |

Using an AI assistant

This repo includes .cursorrules and CLAUDE.md that give Claude Code and Cursor full context about the CLI. You can ask your AI assistant to scaffold a new agent directly:

"Scaffold a new agent called my-bot using the chat template"

The assistant will run the CLI with the correct flags, prompt you for any required secrets, and handle failures automatically.

Scaffold steps

Each step is idempotent and safe to re-run individually. Progress is tracked in .create-agent-state.json in the project directory (gitignored automatically).

| Step | Name | Description | | ---- | ------------------- | -------------------------------------------------------------------------------------------------------------- | | 01 | copy-template | Clones template files from GitHub to the destination directory (via git sparse checkout) | | 02 | fill-placeholders | Replaces name placeholders with the project name | | 03 | write-user-inputs | Writes .dev.vars; patches wrangler.jsonc with non-secret vars | | 04 | gemini-adc-auth | Optional: configures gcloud ADC + quota project and verifies Vertex AI generateContent (see below) | | 05 | npm-install | Runs npm install in the new project | | 06 | db-migrate | Runs npm run db:setup (local D1 schema migration) if the script exists | | 07 | create-resources | Creates Cloudflare resources remotely (D1, KV, R2, Vectorize, Queues) — optional, can be skipped and run later |

Architecture

packages/create-agent/
├── src/
│   ├── create-agent.ts            # Entry point: arg parsing, resolveState(), main()
│   ├── lib/
│   │   ├── template-discovery.ts  # Fetches template manifests from GitHub raw URL
│   │   ├── state.ts               # Read/write .create-agent-state.json
│   │   ├── types.ts               # Shared TypeScript types
│   │   ├── prompts.ts             # Thin wrappers over @clack/prompts
│   │   ├── run.ts                 # spawnSync wrappers (cross-platform, error-safe)
│   │   ├── wrangler-parser.ts     # JSONC parser + resource/placeholder helpers
│   │   └── resource-creators.ts   # Cloudflare resource creation (D1, KV, R2, ...)
│   └── steps/
│       ├── 01-copy-template.ts
│       ├── 02-fill-placeholders.ts
│       ├── 03-write-user-inputs.ts
│       ├── 04-gemini-adc-auth.ts
│       ├── 05-npm-install.ts
│       ├── 06-db-migrate.ts
│       └── 07-create-resources.ts

Key design decisions

• Steps are idempotent — safe to re-run after failures; already-completed work is skipped automatically.
• Secrets never touch the state file — secret inputs go to .dev.vars only, never persisted in .create-agent-state.json.
• wrangler.jsonc is patched as raw text — preserves comments and formatting.
• Windows compatible — interactive prompts work correctly on Windows.

Adding a new template

template.json: the contract between the template and the CLI

Each template has a template.json that declares everything the CLI needs to know: the template name and description shown in the selector, which placeholders to substitute, and what variables to prompt the user for. This file is not copied into the scaffolded project — it's only used during scaffolding.

1. Create the directory: templates/<your-template>/

2. Add required files:

   • wrangler.jsonc — Cloudflare Worker config with placeholders
   • template.json — scaffold manifest (see below)
   • src/ and any other source files

3. Use placeholders in source files and wrangler.jsonc:

   | Placeholder | Replaced with | | ---------------------- | ------------------------------------- | | set_the_agent_name | Project name (e.g. my-bot) | | your-agent | Project name | | {sandbox-account-id} | Cloudflare sandbox account ID | | {prod-account-id} | Left as-is — filled by Terraform/CI | | {sandbox-db-id} | D1 database UUID (created by step 03) | | {ai-gateway-id} | AI Gateway ID |

4. Write template.json:

{
  "name": "My Template",
  "description": "One-line description shown in the selector",
  "placeholders": {
    "set_the_agent_name": "projectName",
    "your-agent": "projectName"
  },
  "userInputs": [
    {
      "key": "ACCOUNT_ID",
      "description": "Cloudflare sandbox account ID",
      "required": true,
      "secret": false,
      "autoFilled": true,
      "placeholder": "{sandbox-account-id}"
    },
    {
      "key": "MY_SECRET",
      "description": "Some API key",
      "required": true,
      "secret": true,
      "devVarsOnly": true
    }
  ]
}

5. Register the template name in packages/create-agent/src/lib/template-discovery.ts:

const TEMPLATE_NAMES = ["chat", "your-template"];

userInputs fields

| Field | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------- | | key | string | Environment variable name | | description | string | Shown as the prompt label | | hint | string? | Shown in parentheses after the description | | required | boolean | Fails the scaffold if left empty | | secret | boolean | Masked input; never written to state file | | autoFilled | boolean? | Value is pre-populated by the CLI (e.g. from wrangler auth); never prompted | | devVarsOnly | boolean? | Only written to .dev.vars, never patched into wrangler.jsonc | | placeholder | string? | The {placeholder} string to replace in wrangler.jsonc |

Cloudflare resources

Step 03 scans wrangler.jsonc env blocks and auto-creates declared resources remotely on Cloudflare:

• D1: entries with "database_id": "{placeholder}" — UUID is fetched and patched back
• KV: entries with "id": "{placeholder}" — ID is fetched and patched back. Set "namespace_name" to control the Cloudflare resource name (falls back to binding if omitted)
• R2 / Vectorize / Queues: always created (name-based, no UUID to patch)

Only env-level resources are created — top-level d1_databases is used for local dev only.

To add a new resource to a template, just declare it in wrangler.jsonc under env.sandbox and env.prod following the conventions above. The CLI requires no changes — step 03 will pick it up automatically when scaffolding a new agent.

To add a new resource to an already-scaffolded project, declare it in the project's wrangler.jsonc (under env.sandbox and env.prod) then re-run step 03:

npx @economic/create-agent --dest ~/projects/my-bot --step create-resources

The resource will be created on Cloudflare and its ID patched back into wrangler.jsonc automatically.