--- title: Commands reference description: Every CoDuck CLI command, organized by what it operates on. category: cli order: 3 agent: "Comprehensive CLI command reference. Auth, projects, files, deploy, generate, env, domains, db, email, storage, stripe, backups, activity, tokens. All commands honor --json and --no-input for agent use." --- # 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](/docs/cli/install). For sign-in, see [Authentication](/docs/cli/auth). ## 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 # 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 # show one project's details coduck create --name # create a new AI-scaffolded project coduck create-existing # import the current directory as a project coduck rename # rename a project coduck delete --yes # delete a project (irreversible) coduck pause # pause (stops billing, keeps state) coduck resume # resume a paused project ``` ## Files ```bash coduck push # upload local files (honors .gitignore + .coduckignore) 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 # print a remote file ``` `push` uploads the source dir from your [`coduck.json`](/docs/reference/coduck-json) and delivers the config file itself (even from a subdirectory). Transient network errors retry automatically; `deploy` warns if your last push failed or local files changed since. ## Deploy ```bash coduck deploy # build + ship the project 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`](/docs/reference/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). ## Generation (AI agent) ```bash coduck generate "add a login page" --wait # send a prompt to the agent coduck jobs status # 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 coduck env set coduck env unset 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](/docs/reference/coduck-json#reserved-environment-variables). `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 ``` ## 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) ``` Read-only by design. No raw connection URL is exposed. ## Backups ```bash coduck backups list coduck backups create coduck backups download --out backup.sql.gz coduck backups restore --yes coduck backups delete ``` ## Email ```bash coduck email status coduck email domains list coduck email domains add example.com coduck email domains dns # reprint DNS records coduck email domains verify coduck email send --from noreply@example.com --to user@example.com \ --subject "Welcome" --text "Thanks." --html "

Thanks.

" coduck email usage # quota coduck email messages # recent messages coduck email suppressions list coduck email suppressions remove coduck email unpause # resume after auto-pause ``` ## Storage ```bash coduck storage list coduck storage upload coduck storage get --out local.bin coduck storage remove ``` ## 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 ``` ## Activity, analytics, forms ```bash coduck activity --limit 100 coduck analytics --days 30 coduck forms list coduck forms read coduck forms delete ``` ## Account + tokens ```bash coduck whoami coduck token status # plan, credits coduck token list # CLI tokens on your account coduck token revoke 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 ``` ## 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 ` | 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 - [Install the CLI](/docs/cli/install) - [Authentication](/docs/cli/auth)