CLI reference

Download the CLI archive, then install the downloaded file:

npm install -g ./setcloud-cli-0.2.0.tgz

setcloud --help lists commands; setcloud <command> --help shows flags. setcloud --version prints the installed version.

Credentials live in ~/.setcloud/credentials.json (owner-only permissions), written by setcloud login. Set SETCLOUD_API_URL to target a different API host — it overrides the saved value.

Auth

`setcloud login`

Authenticate. Opens your browser to authorize the CLI, then saves credentials locally. If the browser can’t open, the terminal prints the URL and a one-time code to enter manually.

setcloud login

`setcloud logout`

Remove saved credentials.

setcloud logout

`setcloud whoami`

Show the authenticated user.

setcloud whoami

Link

`setcloud link`

Link the current directory to a service, so commands that need a service name can find it without you passing one each time.

setcloud link

Services

Container services — see the Compute quickstart.

`setcloud services list`

List your services with status, CPU, memory, and last update time. Use services info for live task counts.

setcloud services list

`setcloud services create`

Create a service interactively: name (lowercase alphanumeric and hyphens, 3–50 chars), container port and health-check path. New services start with 0.25 vCPU and 512 MB of memory and wait at zero running tasks until you deploy an image.

setcloud services create

`setcloud services info <name>`

Show one service: status, CPU, memory, port, task counts, timestamps.

setcloud services info my-api

`setcloud services delete <name>`

Delete a service. Asks for confirmation — this cannot be undone.

setcloud services delete my-api

Projects

Deploy a project straight from a GitHub repository — the first-deploy path. To redeploy an existing service from a local Dockerfile, use deploy [name] instead.

`setcloud projects deploy <repo-url>`

Create and deploy a project from a GitHub repository. Flags: --branch <branch> (default main); --agent — deploy as an AI agent (serverless, scales to zero); --runtime <runtime> — container (default) or serverless.

setcloud projects deploy https://github.com/me/app --branch main

Deploy

`setcloud deploy [name]`

Build the image from the Dockerfile in the current directory, push it to your private registry, and roll the service over. Requires Docker locally. name is optional when you have exactly one service.

Flags: --tag <tag> — image tag (default deploy-<timestamp>).

setcloud deploy my-api --tag v42

`setcloud rollback <name>`

Roll back to the previous deployment.

setcloud rollback my-api

`setcloud scale <name>`

Scale a service. Flags: --count <n> (required, 0–10; zero stops compute and suspends autoscaling).

setcloud scale my-api --count 3

Logs

`setcloud logs <name>`

View service logs. Flags: -f, --follow — keep streaming new entries (Ctrl+C to stop).

setcloud logs my-api --follow

Container commands

Open an interactive shell in a running service, or run one command and return its exit status:

setcloud exec my-api
setcloud exec my-api --command 'node --version' --json
setcloud projects exec 42 --command 'node --version' --json --timeout 30

The image must include /bin/sh. Interactive sessions expire after 30 minutes and disconnect after five minutes without input. Commands have a maximum 300-second runtime and 4 MB of output. Press Ctrl+] to disconnect. Access is scoped to your organization and audited; support sessions cannot open a shell. A lost connection without a confirmed exit status is reported as an error and is never retried automatically.

Environment variables

`setcloud env list <name>`

List a service’s env vars.

setcloud env list my-api

`setcloud env set <name> <pairs...>`

Set one or more KEY=VALUE pairs. Existing keys keep their values unless overwritten.

setcloud env set my-api NODE_ENV=production LOG_LEVEL=info

`setcloud env unset <name> <keys...>`

Remove env vars by key.

setcloud env unset my-api LOG_LEVEL

`setcloud env pull`

Write the linked service’s env vars to a local file. Flags: --file <path> (default .env.local); --force — overwrite without confirmation.

setcloud env pull --file .env.local

Domains

`setcloud domains list`

List your domains with status, expiry, and auto-renew.

setcloud domains list

`setcloud domains info <name>`

Show one domain: status, dates, auto-renew, nameservers.

setcloud domains info example.com

DNS

`setcloud dns list <domain>`

List DNS records — id, type, name, value, TTL.

setcloud dns list example.com

`setcloud dns add <domain> <type> <name> <value>`

Add a record. The type is upcased for you. Flags: --ttl <seconds> (default 300).

setcloud dns add example.com A www 203.0.113.10 --ttl 600

`setcloud dns delete <domain> <recordId>`

Delete a record by id (from dns list).

setcloud dns delete example.com 42

Secrets

Manage secret values, versions, and tags — see the Secrets quickstart. Every secrets command accepts --json for raw JSON output.

`setcloud secrets list`

List all secrets.

setcloud secrets list

`setcloud secrets create <name> <value>`

Create a secret. Flags: --description <desc>.

setcloud secrets create prod/api-key "v3rys3cret" --description "Payments API key"

`setcloud secrets get <name>`

Get a secret’s value and metadata.

setcloud secrets get prod/api-key

`setcloud secrets update <name> <value>`

Update a secret’s value. Creates a new version.

setcloud secrets update prod/api-key "n3wvalue"

`setcloud secrets delete <name>`

Delete with a 7-day recovery window. Flags: --force — delete immediately and permanently, no recovery.

setcloud secrets delete prod/api-key

`setcloud secrets restore <name>`

Restore a secret scheduled for deletion.

setcloud secrets restore prod/api-key

`setcloud secrets batch-get <names...>`

Get multiple secret values at once.

setcloud secrets batch-get prod/api-key prod/db-password

`setcloud secrets versions list <name>`

List all versions of a secret.

setcloud secrets versions list prod/api-key

`setcloud secrets versions move-stage <name> <versionId> <stage>`

Move a staging label to a specific version. Staging labels are custom strings you define — name them whatever fits your release flow.

setcloud secrets versions move-stage prod/api-key 7d3f1a production

Secret rotation

Scheduled rotation integrations are not currently available. setcloud secrets rotate enable returns HTTP 409 with code FEATURE_UNAVAILABLE. Update a value to create a new version; SetCloud does not change the corresponding credentials at the external service. setcloud secrets rotate cancel <name> can cancel an existing schedule.

Secret replicas

Additional replica regions are not currently available. The secrets replicate commands return HTTP 409 with code FEATURE_UNAVAILABLE; secrets remain stored in the project region.

`setcloud secrets policy get <name>`

Get the resource policy attached to a secret.

setcloud secrets policy get prod/api-key

`setcloud secrets policy set <name> <policy>`

Custom resource-policy grants are not currently available. This command returns HTTP 409 with code FEATURE_UNAVAILABLE. Grant application access through project secret links.

`setcloud secrets policy validate <policy>`

Validate the syntax and public-access checks of a policy document without attaching it. Validation does not enable custom policy grants.

`setcloud secrets policy delete <name>`

Remove the resource policy from a secret.

setcloud secrets policy delete prod/api-key

`setcloud secrets tag <name> <pairs...>`

Apply tags as KEY=VALUE pairs.

setcloud secrets tag prod/api-key env=prod team=payments

`setcloud secrets untag <name> <keys...>`

Remove tags by key.

setcloud secrets untag prod/api-key team

`setcloud secrets generate-password`

Generate a random password. Flags: --length <n> (default 32), --no-upper, --no-lower, --no-numbers, --no-symbols.

setcloud secrets generate-password --length 40 --no-symbols

Billing

`setcloud billing balance`

Show your credit balance and auto-reload settings.

setcloud billing balance

`setcloud api GET /api/ai/usage`

AI usage for the current period. Other usage views are available through their documented API routes.

setcloud api GET /api/ai/usage

`setcloud billing transactions`

Credit transaction history — deposits, deductions, balance after each.

setcloud billing transactions

Tokens

Platform API tokens for scripting against the SetCloud API.

`setcloud tokens list`

List your tokens with created/last-used/expiry.

setcloud tokens list

`setcloud tokens create`

Create a token. Flags: --name <name>. The token prints once — save it.

setcloud tokens create --name ci-deploys

`setcloud tokens revoke <id>`

Revoke a token by id.

setcloud tokens revoke 17

Support

`setcloud support list`

List your support tickets.

setcloud support list

`setcloud support create`

Open a ticket interactively: subject, message (opens your $EDITOR), priority (low, normal, high, urgent).

setcloud support create

`setcloud support reply <id> <message>`

Reply to a ticket.

setcloud support reply 311 "Still seeing it after the rollback."

Account

`setcloud account`

Show your profile — name, email, role, company.

setcloud account

Scripts and AI agents

Use a revocable platform token in SETCLOUD_TOKEN for unattended calls. Optionally select an organization with SETCLOUD_ORG_ID. SETCLOUD_API_URL accepts an HTTPS origin; localhost HTTP is available for development.

setcloud api-routes --filter projects
setcloud projects list
setcloud databases
setcloud api GET /api/github/repos
setcloud api POST /api/projects/analyze --data '{"projectId":42,"database":"postgres"}'
setcloud api POST /api/agents --data @agent.json

api writes JSON results to stdout and errors to stderr with a nonzero exit status. --data - reads JSON from stdin. It does not prompt, follow redirects, or automatically repeat a write after a timeout; inspect the resource before retrying an uncertain operation. The server applies the same ownership, role and billing checks as the dashboard. Administrative endpoints require an administrator’s token.

For the OpenAI-compatible AI Gateway, set SETCLOUD_AI_KEY to a gateway key. Platform login tokens and gateway keys are separate. Use stream: false for CLI JSON calls; use the SDK for streaming.

setcloud api GET /v1/models
setcloud api POST /v1/chat/completions --data @request.json

Browser-based GitHub authorization and payment authentication still require the relevant browser flow. JSON API access does not replace those approvals. Container commands use a short-lived, single-use terminal ticket and return the remote exit status; use --command with --json for agents.