#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.

#Chat with the agent

Send a prompt to a project's AI agent, stream the response. Designed for AI agents calling CoDuck programmatically — JSON-first, NDJSON streaming, no interactive prompts.

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-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-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

#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 (AI agent)

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

View raw markdown →Suggest an edit