Command Reference

The complete surface. Pages linked from each section carry the explanation; this one is the index you scan.

Global flags

Accepted by every command, in any position.

Flag	Effect
`-json`	Print the raw API response instead of a table
`-y`, `--yes`	Skip confirmation on destructive commands
`-app NAME`	Target an app by name, slug, or `app_` id
`-project ID`	Scope the request to a project

Environment variables

Variable	Effect
`UNCLOUD_API_URL`	Control-plane URL; overrides `~/.uncloud/config`
`UNCLOUD_API_TOKEN`	Bearer token; overrides `~/.uncloud/config`

Account

Command	Flags	Does
`uncloud login`	`-api URL`	Browser sign-in; writes `~/.uncloud/config`
`uncloud logout`	—	Forget the token on this machine
`uncloud help`	—	Print usage. Also `-h`, `--help`

Ship — details

Command	Flags	Does
`uncloud deploy`	`-name NAME`, `-project ID`	Create the app on first run, then build and watch
`uncloud deploy all`	`-project ID`	Deploy every path in `.uncloud-apps`
`uncloud redeploy`	—	Roll out the current spec
`uncloud status`	—	Watch this app, refreshing every 3s
`uncloud logs`	—	Container logs
`uncloud open`	—	Print the public URL and open it

Configure

Command	Flags	Does
`uncloud env`	—	Print the environment
`uncloud env KEY=value…`	—	Merge and save; `KEY-` unsets
`uncloud scale N`	—	Set replicas and roll out
`uncloud domain list`	—	Hostnames on this app
`uncloud domain add DOMAIN`	—	Attach a hostname, print the DNS record
`uncloud domain rm DOMAIN`	—	Detach a hostname
`uncloud db add`	`-workload dev\|production`, `-storage GB`	Provision Postgres, print `.env`
`uncloud db env`	—	Reprint credentials, create nothing

See Domains and TLS and Databases.

Resources — details

Each takes list, get ID, create key=value…, update ID key=value…, delete ID where supported, plus the verbs listed here.

Resource	Aliases	Supports	Extra verbs
`apps`	`app`	list get create update delete	`deploy` `restart` `status` `logs` `build-log` `pods` `events` `metrics` `deployments` `url` `audit` `secrets`
`databases`	`database`	list get create delete	`credentials`
`droplets`	`droplet` `vms` `vm`	list get create update delete	`actions` `console` `metrics` `events` `snapshots` `snapshot`
`volumes`	`volume`	list get create delete	—
`buckets`	`bucket`	list create delete	`objects` — addressed by `NAME`
`clusters`	`cluster`	list get create delete	`nodes`
`pipelines`	`pipeline`	list create delete	`runs` `trigger`
`backups`	`backup`	list get create update delete	`run`
`webhooks`	`webhook`	list create update delete	—
`tokens`	`api-tokens` `token`	list create delete	—
`ssh-keys`	`keys` `ssh`	list create delete	—
`projects`	`project`	list create	—
`users`	`iam-users`	list create delete	—
`roles`	`iam-roles`	list create delete	—
`groups`	`iam-groups`	list create delete	—
`cronjobs`	`cron`	create	—
`templates`	`launch-templates`	list get create update delete	—
`loadbalancers`	`lb`	list create	—
`security-groups`	`sg`	list create	—
`plans`	—	list create	—
`regions`	—	list	—
`images`	—	list create	—
`nodes`	—	list	—
`events`	—	list	—
`audit`	—	list	—

Verb aliases: ls for list, show for get, new/add for create, set/patch for update, rm/destroy for delete.

Raw API — details

Command	Does
`uncloud api METHOD PATH [key=value…]`	Call any control-plane endpoint

Request bodies

Used by create, update, api, and any verb that sends a body.

Form	Result
`key=value`	String
`key=2`	Number
`key=true` / `key=false`	Boolean
`key=null`	Null
`key={"a":1}` / `key=[1,2]`	Parsed as JSON
`outer.inner=value`	Nested object
`@file.json`	Whole body from a file
`-`	Whole body from stdin

Files

Path	Holds
`~/.uncloud/config`	API URL, token, cached default project — mode `0600`
`.uncloud/config.json`	Directory link: `app_id`, `project_id`, `name`
`.uncloud-apps`	Monorepo app paths, one per line
`uncloud-apps.json`	Same, as `{"apps": [...]}`

Exit codes

Code	Meaning
`0`	Success
`1`	Failure — the API error message is printed to stderr

Common errors

Message	Cause	Fix
`not logged in`	No token on this machine	`uncloud login`
`no app in this directory`	Never deployed here	`uncloud deploy`, or pass `-app`
`no app named "x" in this project`	Name or slug does not match	`uncloud apps list`
`no database attached to this app`	No database for this app	`uncloud db add`
`Refusing to delete without confirmation`	Destructive command, no terminal	Pass `-y`
`401` on any command	Token revoked or expired	`uncloud login`
`403` with a valid token	Token scoped to another project	Check `-project`
Connection refused	Wrong control plane	Set `UNCLOUD_API_URL`, or `uncloud login -api …`

​Global flags

​Environment variables

​Account

​Ship — details

​Configure

​Resources — details

​Raw API — details

​Request bodies

​Files

​Exit codes

​Common errors