@coduckai/cli

The CoDuck command-line interface — hosting, generation, custom domains, database, email, Stripe, storage, and everything else, for humans and agents.

npm install -g @coduckai/cli
coduck login
coduck --help

Design

• One binary, two modes. TTY → human (colors, tables, prompts); piped or --json → machine (NDJSON, no prompts, real exit codes). Auto-detected.
• Total API coverage. Every CoDuck API route has a command — no "use the web app for that" gaps.
• Agent-friendly. Every prompt has a flag; --no-input fails instead of hanging. stdout = data, stderr = chatter.
• Exit codes: 0 ok · 1 generic · 2 usage · 3 auth · 4 not found · 5 conflict · 6 network · 7 server.

For coding agents

If you are already a coding agent, you are the default coder. Inspect, edit, and test the project yourself, then use this CLI for CoDuck project setup, sync, private previews, infrastructure, and deployment.

Do not hand ordinary implementation to coduck chat, coduck ask, or coduck generate just because those commands are available. They invoke a separate CoDuck project agent. Reserve them for an explicit user request or a deliberate special case, such as asking for an independent alternative or working with a project you cannot edit directly.

Common commands

coduck create --name my-app --prompt "build a booking site"  # create + queue generation
coduck create-existing --name my-app   # import an existing project
coduck push                            # upload local files (chunked; honors .coduckignore + .gitignore)
coduck deploy                          # publish live (or update your draft — see below)
coduck changes                         # preview what a publish will change (files + DB schema)
coduck draft update                    # build & run your private draft — Plus/Studio
coduck draft promote                   # publish your draft to your live site
coduck logs --follow --since 30m --grep error
coduck env set KEY value
coduck domains add example.com

coduck create prints the new projectId and generation jobId. Use that project ID with follow-up commands, for example coduck deploy --project <projectId>. If generation cannot be queued after the project is created, the error keeps the project ID and gives a retry command.

Run coduck spec --json for the full, machine-readable command list.

Draft → publish (Plus/Studio)

A draft is a private dev environment (its own database) where you try changes before they go live. coduck deploy is environment-aware:

• Once you coduck draft create, coduck deploy updates your draft by default (your live site is untouched) — preview it, then coduck draft promote to publish.
• No draft ⇒ coduck deploy publishes live, as always.
• Override per-run with --live / --draft, or per-project with "defaultEnv": "draft" | "live" in coduck.json.

coduck changes shows the per-file +/− diff and the database schema additions/removals a publish would apply — before you run it.

Deploy config (coduck.json)

coduck.json is the only file CoDuck reads (other *.toml/*.config files in your repo are unrelated to CoDuck). It's written by create-existing and holds your project's deploy config:

{
  "projectId": "…",
  "dir": "./",            // source root to push/deploy
  "runtime": "node20",
  "install": "npm ci",    // optional — defaults to npm install
  "build": "npm run build",
  "preStart": "npm run migrate",  // optional — runs before start (good for DB migrations)
  "start": "npm start",
  "port": 3000,
  "instanceSize": "small", // small | medium | large (paid plans unlock medium/large)
  "defaultEnv": "live"     // optional — 'draft' or 'live' target for `coduck deploy`
}

push uploads from dir; deploy builds and runs the container using these commands.

Environment variables

coduck env import .env     # bulk import; reserved/invalid keys are skipped (not fatal)
coduck env reserved        # list keys CoDuck manages (rejected on write)

CoDuck injects its own keys (DATABASE_URL, PORT, NODE_ENV, CODUCK_*, …) at deploy time — see coduck env reserved. The managed Postgres starts empty: reach it at DATABASE_URL/DIRECT_URL and bootstrap your schema in your build or preStart command (the platform doesn't expose a raw DB connection URL).

Release

Versioned with git tags. Pushing a v* tag publishes to npm via GitHub Actions (requires the NPM_TOKEN repo secret). coduck --version reads package.json at runtime, so bumping package.json is the single source of truth — no constant to keep in sync.

License

MIT © CoDuckAI

App AI

coduck ai ask "question" --project ID calls the published project's AI and prints its separate credit usage. Add --thinking, --image image.png, or --stream; --json --stream produces NDJSON events. Use --input request.json for full messages/tool definitions and --request-id ID for an exact retry. The CLI returns tool calls without executing them.

coduck ai usage, coduck ai requests, coduck ai capabilities, and coduck ai settings --alert-at 80 all accept --project ID. The SDK, Cloud panel, and agent use the same ledger. Monthly allowances are configured per paid plan (Studio defaults to 25,000); coduck ai usage reports the current allowance; first Cloud publication is required. AI failures do not stop the rest of an app.

Automated callers may supply secret CODUCK_TOKEN and explicit CODUCK_API_URL environment variables without overwriting a saved login. AI prompt arguments are omitted from local command history. Version 0.2.0 requires the companion app-AI API release.

App AI is released gradually by billing account. coduck ai usage includes rollout.status (enabled, not_in_rollout, paused, or unavailable). Requests from accounts outside the rollout or during a pause fail before consuming credits, including streaming requests. Publication and a paid plan alone do not grant rollout access. Administrators use CoDuck Admin → Settings → App AI rollout to add/remove billing-owner emails and set a percentage and monthly allowance independently for Pro, Plus and Studio. Manual accounts bypass percentages, but still require an active paid plan with credits. Changes apply to new requests, preserve spent usage, and a pause blocks all cohorts.