# Helvstack CLI reference

Helvstack is non-interactive by default. Use explicit project, environment, and service scope; request JSON for machine use; plan consequential changes; apply with stable idempotency keys; and wait for operation terminal states. Secret values are write-only.

## Install and orient

Verify the binary, inspect the local contract, and bind the current directory to an explicit project and environment.

- `npm install --global helvstack` — Install with npm
- `uv tool install helvstack` — Install with uv
- `helvstack --json version` — Verify the installed build
- `helvstack capabilities --local` — Read the offline CLI contract
- `helvstack init` — Create a helvstack.yml starter
- `helvstack link` — Link this directory to a project
- `helvstack --json whoami` — Show the scoped identity and target without exposing its token
- `helvstack --json list` — List services in only the linked project and environment
- `helvstack open` — Open the customer console
- `helvstack unlink` — Remove only this directory's link

## Approve scoped access

The CLI opens the SaaS console for human approval and stores a project-scoped token locally. Agents can start and poll the same flow without scraping the browser.

- `helvstack auth login --project <project> --environment production` — Open browser approval and wait
- `helvstack --json auth start --project <project> --environment production` — Start the device flow for an agent
- `helvstack --json auth poll --device-code <code> --wait` — Wait for the approval result
- `helvstack auth status --json` — Inspect local auth without exposing the token
- `helvstack auth logout --revoke` — Revoke the token and remove local config

## Describe services once

helvstack.yml is the reviewed declaration for services, volumes, domains, and links. Validate locally, then plan the remote diff before applying it.

- `helvstack services validate --from helvstack.yml` — Validate without API access
- `helvstack --json services apply --from helvstack.yml --plan` — Preview the remote service diff
- `helvstack --json --idempotency-key services-<sha> services apply --from helvstack.yml` — Apply the reviewed declaration
- `helvstack services retire --plan` — Plan retirement of undeclared services

## Plan, deploy, verify

Consequential actions return operations. Keep the service explicit, use a stable retry key, and wait for a terminal state before calling the deployment complete.

- `helvstack --json up --service web --plan` — Use the familiar plan-first deployment entrypoint
- `helvstack --json deploy --service web --plan` — Review the deployment plan
- `helvstack --json --idempotency-key deploy-<sha> deploy --service web --no-wait` — Queue one idempotent deployment
- `helvstack --json redeploy --service web --plan` — Plan reuse of the latest active immutable image
- `helvstack --json restart --service web --plan` — Plan an immutable rolling restart
- `helvstack --json deployments list --service web` — Inspect deployment history
- `helvstack --json status web` — Check runtime state
- `helvstack --json logs web` — Inspect recent logs
- `helvstack --json metrics --service web --range 1h` — Inspect recent service metrics
- `helvstack --json events web` — Inspect recent service events
- `helvstack rollback --service web --plan` — Review a rollback before applying it

## Variables and domains

Secret values are write-only. Domain activation is staged so ownership, routing, certificates, and rollback can be inspected independently.

- `helvstack --json env list --service web` — List key names only Values are never returned.
- `helvstack env set DATABASE_URL=<value> --service web --plan` — Plan a write-only variable change
- `helvstack env import --from-file .env.production --plan` — Plan a dotenv import
- `helvstack --json run --service web -- npm test` — Validate caller-supplied local variable keys without executing Without --json, the command executes locally; stored values are never decrypted.
- `helvstack shell --service web --env-file .env.local` — Open a local shell using caller-supplied values Stored values remain write-only.
- `helvstack domain add app.example.ch --service web --port 3000 --plan` — Plan a custom domain
- `helvstack domain verification app.example.ch --service web` — Read the ownership TXT challenge
- `helvstack domain cutover-plan app.example.ch --service web` — Inspect DNS, TLS, blockers, and rollback

## Observe and recover

Operation records are the durable receipt for remote mutations. Recovery is guarded and remains plan-first.

- `helvstack --json operations get <operation-id>` — Read one operation
- `helvstack --json operations wait <operation-id> --timeout 10m` — Wait for a terminal operation state
- `helvstack --json operations stale` — List stale running operations
- `helvstack operations recover <operation-id> --plan` — Plan guarded recovery
- `helvstack --json doctor api` — Run read-only deployment diagnosis
- `helvstack --json db report postgres` — Inspect database backup health
- `helvstack --json cache report redis` — Inspect Redis backup and restore health
- `helvstack --json volume list web` — Inspect persistent volumes
- `helvstack --json object-storage objects files --limit 50` — Inspect object storage

## Discover before acting

The CLI exposes the same live contracts to coding agents, CI, direct API clients, and local MCP clients. Start with capabilities; do not guess endpoints or flags.

- `helvstack --json capabilities` — Read the live capability contract
- `helvstack openapi` — Read the live OpenAPI document
- `helvstack mcp serve` — Run the scoped stdio MCP server
- `curl -fsSL https://helvstack.com/llms.txt` — Read the concise machine guide
- `curl -fsSL https://helvstack.com/llms-full.txt` — Read the complete agent contract