CLI Reference

cloady is the command-line interface to the Cloady control plane. Everything it does goes through the same REST API the dashboard uses, so anything you script with it behaves exactly like clicking the UI.

Install


npm install -g cloady

Requires Node 20+. Verify with:


cloady --version

Authentication

The CLI authenticates with a personal API token (cldy_…). Create one in the dashboard under Account → API tokens — the value is shown once, so store it right away:


cloady login
# Paste your Cloady API token: cldy_…
# logged in as you@example.com

login verifies the token against the API before storing it in ~/.config/cloady/config.json (0600; honors $XDG_CONFIG_HOME). cloady logout removes it.

Token resolution order, first match wins:

--token <token> flag
CLOADY_TOKEN environment variable
The stored config file

CI tip: skip login entirely and set CLOADY_TOKEN in the job environment.

Global options

Every command accepts:

Flag	Effect
`--token <token>`	Use this API token for the single invocation
`--api-url <url>`	Point at a different control plane (self-hosted, staging); resolution mirrors the token: flag → `CLOADY_CONTROL_PLANE_URL` → config
`--json`	Print the raw API response as JSON instead of the human-readable line format — the mode to use in scripts

Errors print to stderr as error: <code>: <message> and exit non-zero, so && chains and CI steps fail correctly.

Deploy from a repository

The flagship command. Point it at a repo and it handles the rest:


cloady deploy github.com/your-org/your-repo

What happens with no flags:

Workspace — if you have exactly one, it’s used. Several → an interactive picker. None → the CLI walks you through creating one right there (name, slug, region, plan; if the plan needs payment you get a checkout URL and re-run after completing it).
Region — the workspace’s single activated region, or with several, the one running most of your apps.
Name — the repository name.

The build runs on Cloady infrastructure (your stack is auto-detected), and the app gets a public *.cloady.io URL, printed on success. Private repositories work when the workspace has the GitHub App connected (Settings → Integrations).

Overrides:

Flag	Meaning	Default
`-w, --workspace <slug>`	Target workspace	auto-detected
`--region <region>`	Target region	auto-detected
`--name <name>`	Display name (drives the app id / URL slug)	repo name
`--env <env>`	`prod` · `staging` · `dev`	`prod`
`--branch <branch>`	Git branch to build	repo default
`--subdir <dir>`	Build a subdirectory (monorepos)	repo root
`--port <port>`	Port your server listens on	`3000`


cloady deploy github.com/acme/api --name api --env staging --branch develop --port 8080

Install a catalog application


cloady install <workspace> <applicationId> --region <region>

applicationId is the catalog id (wordpress, postgres, n8n, …) — the same ids the dashboard’s New Application picker shows.

Flag	Meaning
`--region <region>`	Required. Region to install into
`--env <env>`	Environment (default `prod`)
`--name <name>`	Display name; derives the app id
`--value <key=value>`	Configuration value the application declares; repeatable


cloady install acme wordpress --region eu1 --name blog
cloady install acme postgres --region eu1 --value POSTGRES_DB=app

Inspect


cloady whoami                     # the authenticated user
cloady workspaces                 # your workspaces (alias: ws)
cloady regions                    # regions + status
cloady apps <workspace>           # apps in a workspace
cloady apps <workspace> --env prod --region eu1

apps prints one line per app: id, status, region, env, name. Add --json for the full objects (endpoints, versions, components).

Lifecycle

All four take <workspace> <appId> plus --env (default prod) and --region. Region can be omitted when the app id is unambiguous — if the same id exists in several regions you’ll get a region_required error asking you to pass it.


cloady start acme blog            # scale up a stopped app
cloady stop acme blog             # scale to zero (data volumes kept)
cloady redeploy acme blog         # rebuild/refresh code + roll pods
cloady restart acme blog          # alias for redeploy
cloady delete acme blog           # delete the app AND its data

delete is immediate and unprompted — it removes the app’s workloads and persistent volumes. There is no undo.

Run a command in a container


cloady exec <workspace> <appId> --component <name> -- <command…>

Runs a one-off command inside a running container and prints its output; the command’s exit code becomes the CLI’s exit code.

Flag	Meaning
`--component <name>`	Required. Which service of the app to exec into (e.g. `wordpress`, `db`)
`--cwd <dir>`	Working directory (default `/`)
`--env <env>` / `--region <region>`	As above


cloady exec acme blog --component wordpress -- wp plugin list
cloady exec acme db --component postgres -- psql -U app -c 'select 1'

Scripting recipes


# wait until an app reports running
until cloady apps acme --json | jq -e '.[] | select(.svcId=="blog" and .status=="running")' >/dev/null; do sleep 5; done
 
# redeploy from CI on every push to main
CLOADY_TOKEN=$CI_SECRET_TOKEN cloady redeploy acme api
 
# list every app across all workspaces
for ws in $(cloady ws --json | jq -r '.[].slug'); do cloady apps "$ws"; done

For anything the CLI doesn’t cover, drop down to the REST API — same token, same base URL.