CLI Overview - Uncloud

uncloud is a single binary over the same REST API the console uses. Anything the dashboard can do, the CLI can do — apps, databases, droplets, volumes, buckets, domains, pipelines, IAM — and anything it does not model yet is still one uncloud api call away.

Install

npm i -g uncloud-cli

curl -fsSL https://uncloud-cli.vercel.app/install.sh | sh

The Go binaries ship inside the package rather than being fetched afterwards, so installation works behind a proxy, in a locked-down CI runner, and from an npm cache with no network at all. macOS and Linux, x64 and arm64.

uncloud login

This opens your browser, you approve once, and the token is written to ~/.uncloud/config. Nothing is copy-pasted: the token is handed back to a one-shot server bound to 127.0.0.1 that the CLI started itself, and is only accepted when it carries the state nonce generated for that attempt.

Self-hosted control plane

Point the CLI at your own API and it will send you to your own console, where your session actually exists:

uncloud login -api https://api.example.com
uncloud login -api http://localhost:8080

CI, cron, and agents (no browser)

Set two environment variables and skip sign-in entirely. They override ~/.uncloud/config when present:

export UNCLOUD_API_URL=https://api.uncloud.club
export UNCLOUD_API_TOKEN=tok_...

Mint a token with uncloud tokens create name=ci.

The shape of a command

uncloud <command> [subcommand] [arguments] [flags]

Commands fall into three layers:

The daily loop

deploy, status, logs, env, scale, domain, db — the commands you run from a project directory, which need no ids.

Resources

Every control-plane resource, each with list, get, create, update, delete and its own verbs.

Raw API

uncloud api METHOD PATH for anything the other two layers do not cover.

Context: what a bare command means

Most commands need to know which project and which app you mean. Rather than making you type ids, the CLI resolves them in order and stops at the first answer: Project — the -project flag, then .uncloud/config.json in the current directory, then the project cached in ~/.uncloud/config, then your account’s default (fetched once, then cached). App — the -app flag, then .uncloud/config.json in the current directory. -app accepts a name or a slug, not just an app_ id:

uncloud -app wordpress-blog logs      # by name, from anywhere
cd ~/projects/blog && uncloud logs    # by directory, no flag needed

The first uncloud deploy in a directory writes .uncloud/config.json with the app id, project id, and name. Commit it or do not — it only records which app this directory ships to.

Global flags

These work on every command and can be written anywhere in the line:

Flag	Effect
`-json`	Print the raw API response instead of a table. Pipe it into `jq`.
`-y`	Skip the confirmation prompt on destructive commands.
`-app NAME`	Target this app by name, slug, or id, ignoring the directory.
`-project ID`	Scope the request to this project.

Deleting anything asks first. When stdin is not a terminal — CI, a cron job, an agent — there is nobody to ask, so the command refuses rather than assuming yes. Pass -y to mean it.

Output

Lists render as tables, with empty columns dropped so you are not reading a wall of blanks. Everything else prints as indented JSON.

uncloud apps list

ID            NAME            SLUG                 SOURCE_TYPE  IMAGE_URL                REPLICAS  PORT
app_21a90e8e  wpdb            wpdb-21a9            image        mysql:8.0                1         3306
app_08754a47  wordpress-blog  wordpress-blog-0875  image        wordpress:php8.3-apache  1         80

Add -json for anything you intend to parse:

uncloud -json apps list | jq -r '.apps[] | select(.replicas > 1) | .name'

Configuration files

Path	Holds
`~/.uncloud/config`	API URL, token, and the cached default project. Mode `0600`.
`.uncloud/config.json`	Per-directory link: `app_id`, `project_id`, `name`.
`.uncloud-apps`	Monorepo list — one app path per line.
`uncloud-apps.json`	Same list as `{"apps": ["apps/api", "apps/web"]}`.

Environment variables UNCLOUD_API_URL and UNCLOUD_API_TOKEN override the stored config when set.

​Install

​Sign in

​The shape of a command

The daily loop

Resources

Raw API

​Context: what a bare command means

​Global flags

​Output

​Configuration files

Install

Sign in

The shape of a command

Context: what a bare command means

Global flags

Output

Configuration files