#Commands reference

Every CoDuck CLI command, grouped by what it operates on. All commands honor --json (machine-readable output), --no-input (fail instead of prompting), and real exit codes (0 ok, 2 usage, 3 auth, 4 not found, 5 conflict, 6 network, 7 server — full table at the bottom).

For installation, see Install the CLI. For sign-in, see Authentication.

#CoDuck project agent (special cases)

These commands send a prompt to a separate AI agent attached to the CoDuck project and stream its response. They are JSON-first and support NDJSON streaming, but they are not the normal implementation path for Codex, Claude Code, or another capable coding agent that already has the repository.

bash

coduck chat "add a login page"                            # streams response, exits
coduck chat "add a login page" --json                     # NDJSON output for agents
coduck chat "add a login page" --project <id>             # override coduck.json
coduck chat --history                                     # print recent messages
coduck chat --history --json                              # same, as JSON

coduck chat "add a login page"                            # streams response, exits
coduck chat "add a login page" --json                     # NDJSON output for agents
coduck chat "add a login page" --project <id>             # override coduck.json
coduck chat --history                                     # print recent messages
coduck chat --history --json                              # same, as JSON

coduck ask "..." is an alias for coduck chat "...".

#NDJSON event types (what an agent sees with --json)

event	what it means
`chunk` (type=`ttft`)	First token arrived; includes time-to-first-token in ms
`chunk` (type=`text` or `response`)	Streaming response text
`chunk` (type=`tool_call`)	Agent called a tool: `tool`, `path`, args
`chunk` (type=`code`)	Wrote/edited a file: `path`, `content`
`chunk` (type=`preview_url`)	Sandbox boot, ephemeral preview URL
`chunk` (type=`usage`)	Tokens used in this round
`chunk` (type=`complete`)	Generation finished server-side; cost, file list
`complete`	Final summary (mirror of last chunk)
`done`	CLI-side wrap-up event with totals
`paywall`	Insufficient credits; includes plan + upgrade hint
`error`	Failure; includes `message`

#Projects

bash

coduck projects                    # list your projects
coduck project <id>                # show one project's details
coduck create --name <name>        # create a new AI-scaffolded project
coduck create --name <name> --prompt "<prompt>"  # create + queue generation
coduck create-existing             # import the current directory as a project
coduck rename <id> <new>           # rename a project
coduck delete <id> --yes           # delete a project (irreversible)
coduck pause <id>                  # pause (stops billing, keeps state)
coduck resume <id>                 # resume a paused project

coduck projects                    # list your projects
coduck project <id>                # show one project's details
coduck create --name <name>        # create a new AI-scaffolded project
coduck create --name <name> --prompt "<prompt>"  # create + queue generation
coduck create-existing             # import the current directory as a project
coduck rename <id> <new>           # rename a project
coduck delete <id> --yes           # delete a project (irreversible)
coduck pause <id>                  # pause (stops billing, keeps state)
coduck resume <id>                 # resume a paused project

When --prompt is present, create returns both the new projectId and the real queued generation jobId. Use the project ID with follow-up commands such as coduck deploy --project <projectId>. If generation is rejected after the project has been created, the CLI reports that project ID so you can retry without creating a duplicate.

#Files

bash

coduck push                        # upload local files (→ your draft if you have one; see below)
coduck push --prod                 # push straight to live (upload + deploy)
coduck push --draft                # force the draft target (dev environment)
coduck push --dry-run              # show file count, total size, biggest dirs — no upload
coduck push --force                # push even if the server has newer files
coduck pull                        # download project files locally
coduck files ls                    # list remote files
coduck files cat <path>            # print a remote file

coduck push                        # upload local files (→ your draft if you have one; see below)
coduck push --prod                 # push straight to live (upload + deploy)
coduck push --draft                # force the draft target (dev environment)
coduck push --dry-run              # show file count, total size, biggest dirs — no upload
coduck push --force                # push even if the server has newer files
coduck pull                        # download project files locally
coduck files ls                    # list remote files
coduck files cat <path>            # print a remote file

push uploads the source dir from your coduck.json and delivers the config file itself (even from a subdirectory). Transient network errors retry automatically.

push is environment-aware. If your project has a draft, push uploads your files and hot-reloads them into the running draft (~1s via Turbopack; it auto-wakes the draft if it's asleep) — your live site is untouched. push --prod pushes straight to live (upload + deploy). No draft ⇒ push just uploads, and deploy publishes — as before. Every run says where it landed (DRAFT vs LIVE). See Drafts & preview below.

#Deploy

bash

coduck deploy                      # publish live (or update your draft — see below)
coduck deploy --live               # force publish to your live site
coduck deploy --draft              # update your draft (dev environment) instead
coduck deploy --size large         # deploy on a bigger instance (small|medium|large)
coduck stop                        # stop the running container
coduck restart                     # restart with no config change
coduck status                      # current deployment status
coduck teardown --yes              # destroy container + DB + vhost
coduck logs --follow               # tail container logs
coduck logs --since 30m --grep error   # filter by age + pattern
coduck logs-digest                 # summarized error/warn digest

coduck deploy                      # publish live (or update your draft — see below)
coduck deploy --live               # force publish to your live site
coduck deploy --draft              # update your draft (dev environment) instead
coduck deploy --size large         # deploy on a bigger instance (small|medium|large)
coduck stop                        # stop the running container
coduck restart                     # restart with no config change
coduck status                      # current deployment status
coduck teardown --yes              # destroy container + DB + vhost
coduck logs --follow               # tail container logs
coduck logs --since 30m --grep error   # filter by age + pattern
coduck logs-digest                 # summarized error/warn digest

deploy uses the commands + instanceSize from your coduck.json; --size overrides the tier for one deploy. A failed deploy reports the specific cause (out of memory, build failed, wrong port, crashed after start).

deploy is environment-aware (see Drafts & preview below): if the project has a draft, deploy updates the draft by default (your live site is untouched — promote when ready); with no draft it publishes live, as always. Override per run with --live / --draft, or set "defaultEnv" in coduck.json. Every run prints its target (DRAFT vs LIVE).

#Drafts & preview (Plus/Studio)

A draft is a private dev environment (its own database) where you try changes before they go live. Edits — including coduck generate — go to your source, which the draft runs; your live site only changes when you publish.

bash

coduck draft create                # create the draft (its own dev database)
coduck wake                        # wake/pre-warm the draft so pushes hot-reload instantly
coduck push                        # upload + hot-reload into the draft (~1s; auto-wakes it)
coduck changes                     # preview a publish: per-file +/- diff + DB schema add/remove
coduck draft url --open            # open your draft's private preview in the browser
coduck draft status                # is the draft running / asleep?
coduck draft promote               # publish the draft to your live site
coduck draft promote --confirm     # …confirming a destructive DB change (drops); auto-backed-up first
coduck draft delete                # remove the draft; live site untouched

coduck draft create                # create the draft (its own dev database)
coduck wake                        # wake/pre-warm the draft so pushes hot-reload instantly
coduck push                        # upload + hot-reload into the draft (~1s; auto-wakes it)
coduck changes                     # preview a publish: per-file +/- diff + DB schema add/remove
coduck draft url --open            # open your draft's private preview in the browser
coduck draft status                # is the draft running / asleep?
coduck draft promote               # publish the draft to your live site
coduck draft promote --confirm     # …confirming a destructive DB change (drops); auto-backed-up first
coduck draft delete                # remove the draft; live site untouched

Viewing your draft. A draft has no public subdomain — it's a private preview on preview.coduck.ai behind a short-lived signed token (only you can open it). coduck draft url prints that link (--open launches it); coduck push and coduck wake also print it on success. The link is good for about an hour — re-run coduck draft url for a fresh one.

The fast loop: with a warm draft (coduck wake once), each coduck push hot-reloads your changes in about a second — same feel as a local dev server — while your live site stays put. coduck draft update (aliases deploy, wake) does the same refresh without an upload; it only cold-boots (~60–90s) when the draft is asleep. promote (alias publish) ships the draft to live.

Drafts are a Plus/Studio feature — other plans get a clear message. Everything is --json-friendly for agents; the typical headless loop is edit → coduck push → coduck changes → coduck draft promote.

#Generation with the CoDuck project agent (special cases)

The same ownership rule applies here: an outer coding agent should implement changes itself by default. Use background generation only when invoking CoDuck's separate project agent is intentional.

bash

coduck generate "add a login page" --wait    # send a prompt to the agent
coduck jobs status <jobId>                   # check a running generation
coduck jobs messages                         # conversation history

coduck generate "add a login page" --wait    # send a prompt to the agent
coduck jobs status <jobId>                   # check a running generation
coduck jobs messages                         # conversation history

#Environment variables

bash

coduck env list                    # list env vars (values masked)
coduck env list --reveal           # show full values
coduck env get <key>
coduck env set <key> <value>
coduck env unset <key>
coduck env import .env             # bulk import (skips reserved/invalid keys, imports the rest)
coduck env reserved                # list the keys CoDuck manages (can't be set)

coduck env list                    # list env vars (values masked)
coduck env list --reveal           # show full values
coduck env get <key>
coduck env set <key> <value>
coduck env unset <key>
coduck env import .env             # bulk import (skips reserved/invalid keys, imports the rest)
coduck env reserved                # list the keys CoDuck manages (can't be set)

A set of keys are reserved (CoDuck injects them and rejects them on write): DATABASE_URL, DIRECT_URL, PORT, NODE_ENV, and everything under CODUCK_* / NEXT_PUBLIC_CODUCK_*. coduck env reserved prints the authoritative list; see the coduck.json reference. coduck env import skips reserved/invalid keys with a warning instead of aborting.

#Custom domains

bash

coduck domains list
coduck domains add example.com
coduck domains verify example.com
coduck domains remove example.com
coduck domains transfer example.com <new-projectId>

coduck domains list
coduck domains add example.com
coduck domains verify example.com
coduck domains remove example.com
coduck domains transfer example.com <new-projectId>

#Database

bash

coduck db schema                   # full schema as JSON
coduck db tables                   # list tables
coduck db tables --table users     # read rows from a table
coduck db users                    # auth users (if using @coduckai/sdk/auth)

coduck db schema                   # full schema as JSON
coduck db tables                   # list tables
coduck db tables --table users     # read rows from a table
coduck db users                    # auth users (if using @coduckai/sdk/auth)

Read-only by design. No raw connection URL is exposed.

#Backups

bash

coduck backups list
coduck backups create
coduck backups download <id> --out backup.sql.gz
coduck backups restore <id> --yes
coduck backups delete <id>

coduck backups list
coduck backups create
coduck backups download <id> --out backup.sql.gz
coduck backups restore <id> --yes
coduck backups delete <id>

#Email

bash

coduck email status
coduck email domains list
coduck email domains add example.com
coduck email domains dns <id>      # reprint DNS records
coduck email domains verify <id>
coduck email send --from noreply@example.com --to user@example.com \
  --subject "Welcome" --text "Thanks." --html "<p>Thanks.</p>"
coduck email usage                 # quota
coduck email messages              # recent messages
coduck email suppressions list
coduck email suppressions remove <id>
coduck email unpause               # resume after auto-pause

coduck email status
coduck email domains list
coduck email domains add example.com
coduck email domains dns <id>      # reprint DNS records
coduck email domains verify <id>
coduck email send --from noreply@example.com --to user@example.com \
  --subject "Welcome" --text "Thanks." --html "<p>Thanks.</p>"
coduck email usage                 # quota
coduck email messages              # recent messages
coduck email suppressions list
coduck email suppressions remove <id>
coduck email unpause               # resume after auto-pause

#Storage

bash

coduck storage list
coduck storage upload <file>
coduck storage get <name> --out local.bin
coduck storage remove <name>

coduck storage list
coduck storage upload <file>
coduck storage get <name> --out local.bin
coduck storage remove <name>

#Stripe (BYOS payments)

bash

coduck stripe connect              # print OAuth URL
coduck stripe status
coduck stripe disconnect --yes
coduck stripe payments stats
coduck stripe payments transactions
coduck stripe payments revenue --days 30
coduck stripe payments health

coduck stripe connect              # print OAuth URL
coduck stripe status
coduck stripe disconnect --yes
coduck stripe payments stats
coduck stripe payments transactions
coduck stripe payments revenue --days 30
coduck stripe payments health

#Activity, analytics, forms

bash

coduck activity --limit 100
coduck analytics --days 30
coduck forms list
coduck forms read <id>
coduck forms delete <id>

coduck activity --limit 100
coduck analytics --days 30
coduck forms list
coduck forms read <id>
coduck forms delete <id>

#Account + tokens

bash

coduck whoami
coduck token status                # plan, credits
coduck token list                  # CLI tokens on your account
coduck token revoke <id>
coduck token show --confirm        # print the JWT (refuses without --confirm)

coduck whoami
coduck token status                # plan, credits
coduck token list                  # CLI tokens on your account
coduck token revoke <id>
coduck token show --confirm        # print the JWT (refuses without --confirm)

#Discovery

bash

coduck --help                      # human-friendly help
coduck --help --json               # machine-readable spec (use this to build an MCP wrapper)
coduck version
coduck doctor                      # diagnose auth + config + connectivity

coduck --help                      # human-friendly help
coduck --help --json               # machine-readable spec (use this to build an MCP wrapper)
coduck version
coduck doctor                      # diagnose auth + config + connectivity

#Global flags

Flag	What it does
`--json`	Force JSON output regardless of TTY
`--no-input`	Fail with exit 2 instead of prompting
`--quiet`	Suppress non-essential output
`--project <id>`	Override the `coduck.json` projectId for this command

#Exit codes

Code	Meaning
0	Success
1	Generic error
2	Usage error (bad flag, missing input under `--no-input`)
3	Authentication error
4	Not found
5	Conflict (e.g. payment required / state conflict)
6	Network error
7	Server error (5xx)

#Next

#App AI

Use the same model and app-AI credit pool as the SDK. Requires a published project and an eligible Studio plan. These credits are independent of build-generation credits.

bash

coduck ai ask "Summarize our product in one sentence" --project PROJECT_ID
coduck ai ask "What is in this photo?" --image photo.png --project PROJECT_ID
coduck ai ask "Compare these options" --thinking --stream --project PROJECT_ID
coduck --json ai ask --input request.json --stream --project PROJECT_ID
coduck ai usage --project PROJECT_ID
coduck ai requests --project PROJECT_ID
coduck ai settings --project PROJECT_ID --alert-at 80
coduck ai capabilities --project PROJECT_ID

coduck ai ask "Summarize our product in one sentence" --project PROJECT_ID
coduck ai ask "What is in this photo?" --image photo.png --project PROJECT_ID
coduck ai ask "Compare these options" --thinking --stream --project PROJECT_ID
coduck --json ai ask --input request.json --stream --project PROJECT_ID
coduck ai usage --project PROJECT_ID
coduck ai requests --project PROJECT_ID
coduck ai settings --project PROJECT_ID --alert-at 80
coduck ai capabilities --project PROJECT_ID

Advanced JSON input uses the SDK chat shape: messages, tools, thinking, and max_tokens. Raw tool calls are returned; the CLI does not execute arbitrary tools. The SDK's bounded ai.run helper can run handlers in your own server.

The CLI prints a request ID to stderr. Use --request-id SAME_ID only to retry the same logical request. --json --stream prints newline-delimited events; the complete event confirms final usage. Prompt contents are omitted from local CLI history.

Automated agents can supply CODUCK_TOKEN with an explicit CODUCK_API_URL instead of replacing a saved login. Keep the token in a secret environment variable, never in source or logs.

View raw markdown →Suggest an edit