HelvstackDocs
CLI reference

Commands humans remember.
Contracts agents can trust.

Helvstack is explicit where production demands it: scope, plan, idempotency, operation state, and proof. Every example below is copyable and machine-friendly.

Deploy with an agent
01DiscoverCapabilities before guesses02PlanRead the remote diff03ApplyOne stable retry key04VerifyWait and return evidence
Start here

Install and orient

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

Terminal
  1. npm install --global helvstackInstall with npm
  2. uv tool install helvstackInstall with uv
  3. helvstack --json versionVerify the installed build
  4. helvstack capabilities --localRead the offline CLI contract
  5. helvstack initCreate a helvstack.yml starter
  6. helvstack linkLink this directory to a project
  7. helvstack --json whoamiShow the scoped identity and target without exposing its token
  8. helvstack --json listList services in only the linked project and environment
  9. helvstack openOpen the customer console
  10. helvstack unlinkRemove only this directory's link
Authentication

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.

Terminal
  1. helvstack auth login --project <project> --environment productionOpen browser approval and wait
  2. helvstack --json auth start --project <project> --environment productionStart the device flow for an agent
  3. helvstack --json auth poll --device-code <code> --waitWait for the approval result
  4. helvstack auth status --jsonInspect local auth without exposing the token
  5. helvstack auth logout --revokeRevoke the token and remove local config
Project model

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.

Terminal
  1. helvstack services validate --from helvstack.ymlValidate without API access
  2. helvstack --json services apply --from helvstack.yml --planPreview the remote service diff
  3. helvstack --json --idempotency-key services-<sha> services apply --from helvstack.ymlApply the reviewed declaration
  4. helvstack services retire --planPlan retirement of undeclared services
Deployment

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.

Terminal
  1. helvstack --json up --service web --planUse the familiar plan-first deployment entrypoint
  2. helvstack --json deploy --service web --planReview the deployment plan
  3. helvstack --json --idempotency-key deploy-<sha> deploy --service web --no-waitQueue one idempotent deployment
  4. helvstack --json redeploy --service web --planPlan reuse of the latest active immutable image
  5. helvstack --json restart --service web --planPlan an immutable rolling restart
  6. helvstack --json deployments list --service webInspect deployment history
  7. helvstack --json status webCheck runtime state
  8. helvstack --json logs webInspect recent logs
  9. helvstack --json metrics --service web --range 1hInspect recent service metrics
  10. helvstack --json events webInspect recent service events
  11. helvstack rollback --service web --planReview a rollback before applying it
Configuration

Variables and domains

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

Terminal
  1. helvstack --json env list --service webList key names onlyValues are never returned.
  2. helvstack env set DATABASE_URL=<value> --service web --planPlan a write-only variable change
  3. helvstack env import --from-file .env.production --planPlan a dotenv import
  4. helvstack --json run --service web -- npm testValidate caller-supplied local variable keys without executingWithout --json, the command executes locally; stored values are never decrypted.
  5. helvstack shell --service web --env-file .env.localOpen a local shell using caller-supplied valuesStored values remain write-only.
  6. helvstack domain add app.example.ch --service web --port 3000 --planPlan a custom domain
  7. helvstack domain verification app.example.ch --service webRead the ownership TXT challenge
  8. helvstack domain cutover-plan app.example.ch --service webInspect DNS, TLS, blockers, and rollback
Operations

Observe and recover

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

Terminal
  1. helvstack --json operations get <operation-id>Read one operation
  2. helvstack --json operations wait <operation-id> --timeout 10mWait for a terminal operation state
  3. helvstack --json operations staleList stale running operations
  4. helvstack operations recover <operation-id> --planPlan guarded recovery
  5. helvstack --json doctor apiRun read-only deployment diagnosis
  6. helvstack --json db report postgresInspect database backup health
  7. helvstack --json cache report redisInspect Redis backup and restore health
  8. helvstack --json volume list webInspect persistent volumes
  9. helvstack --json object-storage objects files --limit 50Inspect object storage
Agent interfaces

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.

Terminal
  1. helvstack --json capabilitiesRead the live capability contract
  2. helvstack openapiRead the live OpenAPI document
  3. helvstack mcp serveRun the scoped stdio MCP server
  4. curl -fsSL https://helvstack.com/llms.txtRead the concise machine guide
  5. curl -fsSL https://helvstack.com/llms-full.txtRead the complete agent contract
Still looking for a command?

Run helvstack capabilities --local for the installed contract, then helvstack capabilities for the live platform contract.