Reference
The cli command
Install the cli command, sign in, link a folder, and look up any command and its flags.
cli is the command-line tool for people who prefer a terminal, and for automated builds. It does everything the dashboard does.
How to do it: install it with npm i -g @clicloud-app/cli, run cli login, then cli up in your project folder to deploy it.
Only packages named @clicloud-app/... are CLI's own. The technical version lists every command.
The cli command lets you deploy and run apps on CLI from a terminal or a CI job. It talks to the same API as the dashboard and agents, so anything you do here shows up there. Every command takes --json for machine-readable output.
Install
npm i -g @clicloud-app/cliOnly @clicloud-app packages are CLI's. The older @clicloud/cli on npm is someone else's: don't install it.
Or with Homebrew:
brew install clicloud-app/tap/clicloudThe package installs cli (also available as clicloud) and cli-mcp, the MCP server agents use. For agent apps, the MCP server also comes on its own as @clicloud-app/mcp (npx -y @clicloud-app/mcp); see Install in your agent app.
Run cli help (or cli --help) for the built-in summary.
Sign in
cli loginBy default this asks for your email, sends you a 6-digit code, and asks for the code. You can pass the address up front:
cli login --email [email protected]For CI, use a token instead:
cli login --token cli_…Your session is saved in ~/.config/cli/config.json, readable only by you. cli whoami shows who you're signed in as and cli logout forgets the session.
Link a folder
Most commands work on "the linked project" and "the linked service", so you don't have to pass ids every time. The link lives in a .cli.json file in your folder (no secrets in it). cli looks for it in the current folder and its parents, the way git looks for .git.
cli init my-app # create a project and link this folder
cli link # pick an existing project from a list
cli link --project prj_… --service web
cli unlinkThe first cli up in a linked folder creates a service if there isn't one and records it in the link.
To work on something other than the link for one command, pass --project or --service. To run a command against an environment such as staging, pass -e staging (or set CLI_ENVIRONMENT).
Options that work everywhere
| Option | What it does |
|---|---|
--json | Print machine-readable JSON instead of text |
--project <id> | Use this project instead of the linked one |
--service <name> | Use this service instead of the linked one |
-e, --environment <name> | Run against an environment (staging, dev…) |
--dry-run | On deploy, scale, volume, db create, template and rm: show the plan and cost without changing anything |
--api <url> | Talk to another CLI server for this command |
-h, --help | Show the help text |
| Environment variable | What it does |
|---|---|
CLI_TOKEN | Session token; overrides the saved config |
CLI_API_URL | The CLI server; overrides the saved config |
CLI_ENVIRONMENT | Default environment, like -e |
CLI_APPROVAL | An approval id to send with changes, after a person approved the request (see /docs/approvals) |
CLI_CONFIG_DIR | Where to keep the saved session instead of ~/.config/cli |
CLI_REGISTRY_USER, CLI_REGISTRY_PASSWORD | Login for a private image in cli add --image |
RAILWAY_TOKEN, HEROKU_API_KEY | Used by cli import --from |
Getting started
| Command | What it does |
|---|---|
cli login [--email [email protected]] [--token cli_…] | Sign in (email code by default) |
cli logout | Forget the saved session |
cli whoami | Who you're signed in as |
cli init [name] | Create a project and link this folder to it |
cli link [--project id] [--service name] | Link this folder to an existing project |
cli unlink | Remove this folder's link |
cli projects | List your projects and their credit (cli projects create [name] makes one without linking) |
Deploying
| Command | What it does |
|---|---|
cli up [path] [--service name] [--port n] [--message text] [--detach] | Upload this folder and deploy it. Respects .gitignore and .cliignore; --detach (-d) returns without watching |
cli add postgres|mysql|redis|mongo [--name n] | Add a database and connect it to the service |
cli add --image <ref> [--name n] [--port n] [--start "cmd"] | Add a service from a Docker image and deploy it (private images: CLI_REGISTRY_USER / CLI_REGISTRY_PASSWORD) |
cli deploy [--service name] | Redeploy from the service's source |
cli status | Services, URLs and recent deploys |
cli logs [-f] [-n lines] [--deploy id] | App output (follow with -f), or a deploy's build logs |
cli logs [--grep text|/regex/] [--level error|warn] | Search the last 5000 lines |
cli open | Open the service's URL |
cli rm [service] [--delete-data] [--yes] | Delete a service (its data is kept unless --delete-data) |
cli up -m "fix checkout"
cli logs -f
cli logs --grep "/timeout|ECONNRESET/" --level errorWhen a deploy fails, cli up and cli deploy print the error code, the evidence lines and the steps to fix it, then exit with a non-zero code. See Error codes.
Configuration
| Command | What it does |
|---|---|
cli env | List variables |
cli env set KEY=value … [--plain] | Set variables (hidden unless --plain) |
cli env unset KEY … | Remove variables |
cli env import [file] | Set variables from a .env file (default .env) |
cli env check | Check that every ${{service.KEY}} reference resolves |
cli vars | Project-wide shared variables (use as ${{shared.KEY}}) |
cli vars set KEY=value … | cli vars unset KEY … | Change shared variables |
cli domains | List domains |
cli domains generate [name] | Get a hosted <name>.<app domain> address |
cli domains add <hostname> | Add your own domain (prints DNS records) |
cli domains verify <id> | cli domains rm <id> | Check DNS / remove a domain |
See Variables and configuration and Domains and networking.
Databases
| Command | What it does |
|---|---|
cli db create postgres|mysql|redis|mongo [--name n] [--link] | Create a private database (--link: connect it to the service) |
cli db link <database> [--var NAME] | Give the service its connection URL |
cli db backups <database> | List backups |
cli db backup <database> | Back up now |
cli db restore <backupId> [--yes] | Replace the data with a backup |
cli db query <database> "<sql>" [--write] | Query Postgres or MySQL (read-only unless --write) |
cli db tables <database> | List tables with row counts |
cli db connect <database> [--public|--private] | Connection URL; --public opens a port for your machine |
See Databases.
Running
| Command | What it does |
|---|---|
cli scale <n> | Run n copies behind the address (next deploy) |
cli volume add <path> | cli volume rm | Persistent disk for the service (next deploy) |
cli sleep <minutes>|off | Sleep after this long without traffic (wakes on request) |
cli gpu [kind [count] | off] | GPUs for the service (no argument: what's offered) |
cli health | Up or down, uptime and recent incidents |
cli cron | List cron jobs (schedules are UTC) |
cli cron add <name> "<schedule>" "<command>" | Add a job, e.g. cli cron add backup "0 3 * * *" "node backup.js" |
cli cron run|logs|pause|resume|rm <name> | Run now, last output, pause, resume, delete |
See Scaling and running.
Environments
| Command | What it does |
|---|---|
cli environments | Production and its copies (staging, dev…) |
cli environments create <name> [--from env] | Copy services and variables, with fresh databases |
cli environments rm <name> | Delete an environment and its data |
-e, --environment <name> | Run any command against an environment |
Running locally and remotely
| Command | What it does |
|---|---|
cli run <command…> | Run a local command with the service's variables |
cli dev [--tunnel port] [--no-db] <command…> | Like run, with the project's databases opened to this machine for 4 hours (--tunnel: public URL as PUBLIC_URL) |
cli tunnel <port> [--name n] | A public https address for a port on this machine |
cli exec "<command>" | Run a command in the live container |
cli shell | A command prompt inside the live container |
cli run npm run dev
cli dev --tunnel 3000 npm run dev
cli exec "npx prisma migrate status"Storage, queues and GPUs
| Command | What it does |
|---|---|
cli buckets | cli bucket create <name> [--public] | Object storage (the linked service gets BUCKET_URL / BUCKET_TOKEN) |
cli bucket put <bucket> <file> [key] | Upload a file |
cli bucket url <bucket> <key> [--days n] | A link anyone can open until it expires |
cli queues | cli queue create <name> [--push /p] | Message queues (pull, or pushed to the service at /p) |
See Buckets, queues and secrets.
Templates and moving in
| Command | What it does |
|---|---|
cli templates | One-click stacks you can deploy |
cli template <id> [key=value …] | Deploy one into this project (inputs as key=value) |
cli import [provider] [--apply] | Recreate a Railway, Heroku, Render, Fly, Vercel or Compose setup here |
cli import … --from <railway project|heroku app> | Read the whole setup through their API (RAILWAY_TOKEN / HEROKU_API_KEY) |
cli import shows the plan first; add --apply to create everything.
Agents and safety
| Command | What it does |
|---|---|
cli approvals | Requests from agents waiting for a person |
cli approve <id> | cli deny <id> | Decide one |
cli keys | API keys for agents and CI |
cli keys create <name> [--role agent] [--days 90] [--cap usd] | Create a key |
cli keys revoke <id> | cli keys revoke-all | Revoke one, or every key and agent at once |
cli changes [id] [approve|reject] | Changes agents proposed, built as previews |
cli agents | Agents' track records (score, deploys, undos) |
cli events [-f] [--kinds deploy_failed,…] | What happened in the project (follow with -f) |
cli notify | Alert channels |
cli notify add slack|discord <webhook-url> | Send alerts to Slack or Discord |
cli notify add telegram <bot-token> <chat-id> | Send alerts to Telegram |
cli notify test|rm <id> | Send a test message / remove a channel |
See Agent permissions and limits, Approvals and Monitoring and logs.
Debugging
| Command | What it does |
|---|---|
cli ask "<question>" | Ask the service's logs, deploys and errors a question |
cli errors [id] [--all] | Grouped exceptions from the app (OpenTelemetry) |
cli errors resolve|ignore|reopen <id> | Mark one |
cli traces [--slow] [--failed] | Recent requests with timings, and the slowest routes |
See Monitoring and logs.
Money
| Command | What it does |
|---|---|
cli usage [--hours 24] | Spend, burn rate, runway and plan advice |
cli topup <usd> | Add credit by card (opens checkout) |
cli deposit [card <usd>] | This project's USDC deposit address, or pay by card |
cli statement [YYYY-MM] [--csv] | The month's statement (printable or for accounting) |
cli earnings | What paid routes, streams and subscriptions earned |
cli withdraw <usd> <address> [--network n] | Send earnings to a wallet (owners; second factor) |
cli find <words> [--tag t] | Search the directory of paid APIs |
See Credit, pricing and billing, Selling your API and tools and Paying for other APIs.
Secrets and trust
| Command | What it does |
|---|---|
cli secrets | Syncs and rotations |
cli secrets sync doppler <token> [--shared] [--redeploy] | Keep variables in step with Doppler (also vault, http); --shared into shared variables, --redeploy on change |
cli secrets rotate <KEY> [--every days] | Rotate a secret now and on a schedule (databases: no KEY) |
cli receipts [on|off] | Seal the audit log on chain |
Team
| Command | What it does |
|---|---|
cli members | Who has access, and their roles |
cli members add <email> [--role developer] | Invite someone (viewer, developer, admin) |
cli members rm <email|wallet> | Remove someone |
cli audit [-n 20] | Who changed what |
See Teams and security.
Dry runs
--dry-run works on deploy, scale, volume, db create, template and rm. CLI prints the plan (what changes, the hourly cost before and after, restarts) and changes nothing.
cli scale 3 --dry-run
cli rm old-worker --dry-runJSON output
Add --json to any command for output you can parse, for example in CI:
cli status --json | jq -r '.services[].name'
cli up --json --detachWith --json, an API error is printed as the standard error envelope with code, message, remediation and retry (see /docs/errors).
Exit codes
| Code | Meaning |
|---|---|
0 | It worked (for cli up and cli deploy: the deploy went live) |
1 | The API refused the request, or the deploy failed |
2 | The command was used wrongly, for example a missing argument or an unlinked folder |
When a change needs approval
If the project's rules make a change wait for a person, cli prints what it's waiting for and a link to approve or deny it. Once it's approved, run the same command again with the approval id:
CLI_APPROVAL=apr_… cli rm old-workerSee Approvals.