Docs menu

Reference

The cli command

Install the cli command, sign in, link a folder, and look up any command and its flags.

Explain it

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

Terminal
npm i -g @clicloud-app/cli

Only @clicloud-app packages are CLI's. The older @clicloud/cli on npm is someone else's: don't install it.

Or with Homebrew:

Terminal
brew install clicloud-app/tap/clicloud

The 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

Terminal
cli login

By default this asks for your email, sends you a 6-digit code, and asks for the code. You can pass the address up front:

Terminal
cli login --email [email protected]

For CI, use a token instead:

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

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.

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

The 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

OptionWhat it does
--jsonPrint 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-runOn 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, --helpShow the help text
Environment variableWhat it does
CLI_TOKENSession token; overrides the saved config
CLI_API_URLThe CLI server; overrides the saved config
CLI_ENVIRONMENTDefault environment, like -e
CLI_APPROVALAn approval id to send with changes, after a person approved the request (see /docs/approvals)
CLI_CONFIG_DIRWhere to keep the saved session instead of ~/.config/cli
CLI_REGISTRY_USER, CLI_REGISTRY_PASSWORDLogin for a private image in cli add --image
RAILWAY_TOKEN, HEROKU_API_KEYUsed by cli import --from

Getting started

CommandWhat it does
cli login [--email [email protected]] [--token cli_…]Sign in (email code by default)
cli logoutForget the saved session
cli whoamiWho 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 unlinkRemove this folder's link
cli projectsList your projects and their credit (cli projects create [name] makes one without linking)

Deploying

CommandWhat 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 statusServices, 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 openOpen the service's URL
cli rm [service] [--delete-data] [--yes]Delete a service (its data is kept unless --delete-data)
Terminal
cli up -m "fix checkout"
cli logs -f
cli logs --grep "/timeout|ECONNRESET/" --level error

When 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

CommandWhat it does
cli envList 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 checkCheck that every ${{service.KEY}} reference resolves
cli varsProject-wide shared variables (use as ${{shared.KEY}})
cli vars set KEY=value … | cli vars unset KEY …Change shared variables
cli domainsList 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

CommandWhat 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

CommandWhat it does
cli scale <n>Run n copies behind the address (next deploy)
cli volume add <path> | cli volume rmPersistent disk for the service (next deploy)
cli sleep <minutes>|offSleep after this long without traffic (wakes on request)
cli gpu [kind [count] | off]GPUs for the service (no argument: what's offered)
cli healthUp or down, uptime and recent incidents
cli cronList 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

CommandWhat it does
cli environmentsProduction 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

CommandWhat 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 shellA command prompt inside the live container
Terminal
cli run npm run dev
cli dev --tunnel 3000 npm run dev
cli exec "npx prisma migrate status"

Storage, queues and GPUs

CommandWhat 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

CommandWhat it does
cli templatesOne-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

CommandWhat it does
cli approvalsRequests from agents waiting for a person
cli approve <id> | cli deny <id>Decide one
cli keysAPI 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-allRevoke one, or every key and agent at once
cli changes [id] [approve|reject]Changes agents proposed, built as previews
cli agentsAgents' track records (score, deploys, undos)
cli events [-f] [--kinds deploy_failed,…]What happened in the project (follow with -f)
cli notifyAlert 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

CommandWhat 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

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

CommandWhat it does
cli secretsSyncs 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

CommandWhat it does
cli membersWho 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.

Terminal
cli scale 3 --dry-run
cli rm old-worker --dry-run

JSON output

Add --json to any command for output you can parse, for example in CI:

Terminal
cli status --json | jq -r '.services[].name'
cli up --json --detach

With --json, an API error is printed as the standard error envelope with code, message, remediation and retry (see /docs/errors).

Exit codes

CodeMeaning
0It worked (for cli up and cli deploy: the deploy went live)
1The API refused the request, or the deploy failed
2The 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:

Terminal
CLI_APPROVAL=apr_… cli rm old-worker

See Approvals.