CLI Reference

The HostStack CLI lets you drive every dashboard action from a terminal — ideal for scripts, CI steps, and local development.

Installation

npm

npm install -g @hoststack.dev/cli

bun

bun add -g @hoststack.dev/cli

Requires Node 18+ or Bun 1.1+.

Authentication

Mint an API key at Settings → API Keys in the dashboard, then persist it on this machine. The CLI stores the key at ~/.hoststack/config.json with file mode 0600. You can also export HOSTSTACK_API_KEY instead — env vars take precedence over the config file.

bash

hoststack login --key hs_live_your_api_key
hoststack whoami

Use hs_test_… keys against a test team for staging / CI; hs_live_… keys carry full-access permissions on the production team. Pass --url to login to authenticate against a self-hosted HostStack control plane.

Command Reference

Authentication

Command	Usage	Description
`hoststack login`	`hoststack login --key hs_live_... [--url https://api.example.com]`	Authenticate and persist the API key locally
`hoststack whoami`	`hoststack whoami`	Show the current user, team, and API endpoint

Projects

Command	Usage	Description
`hoststack projects list`	`hoststack projects list [--json]`	List all projects in the active team
`hoststack projects create`	`hoststack projects create --name "My Project" [--description "..."] [--region eu-central-1]`	Create a new project
`hoststack projects delete`	`hoststack projects delete <project-id>`	Delete a project

Services

Command	Usage	Description
`hoststack services list`	`hoststack services list [--json]`	List services across all projects
`hoststack services get`	`hoststack services get <service-id>`	Show service details
`hoststack services create`	`hoststack services create --name my-app --type <web_service\|private_service\|worker\|cron_job\|static_site> --project <project-id\|prj_…>`	Create a new service
`hoststack services delete`	`hoststack services delete <service-id>`	Delete a service
`hoststack services scale`	`hoststack services scale <service-id> <min[:max]>`	Scale to N replicas
`hoststack services suspend`	`hoststack services suspend <service-id>`	Suspend a service (keep its data, stop traffic)
`hoststack services resume`	`hoststack services resume <service-id>`	Resume a suspended service

Dev environments

Command	Usage	Description
`hoststack dev new`	`hoststack dev new [--name <name>] [--github-id <n> \| --repo <git-url>] [--branch <name>] [--db postgres,redis,meilisearch] [--plan <size>]`	Create a standalone dev box in the team Development area — from a connected GitHub repo, any clone URL, or blank. --db attaches fresh companion databases alongside it.
`hoststack dev list`	`hoststack dev list`	List your dev environments and their companion services (alias: ls)
`hoststack dev create`	`hoststack dev create --project <project-id\|prj_…> [--name <name>] [--size <plan>] [--disk <gb>] [--repo <git-url>] [--branch <name>] [--hoststack-key <key>] [--poststack-key <key>] [--env KEY=VALUE] [--no-deploy]`	Create a dev box inside a project. --repo is cloned into /workspace on first boot; --no-deploy creates and configures it without firing that deploy.
`hoststack dev create --service`	`hoststack dev create --service <service-id\|svc_…> [--no-db] [--name <name>]`	Spin up a dev box from an existing service: a clone of the app with its env vars, its linked database cloned (unless --no-db), and its own dev URL.
`hoststack dev delete`	`hoststack dev delete <service-id\|svc_…>`	Tear a dev box down together with its cloned database and /workspace volume (alias: rm)

Deploys

Command	Usage	Description
`hoststack deploy trigger`	`hoststack deploy trigger <service-id> [--commit <hash>] [--branch <name>] [--clear-cache]`	Trigger a new deploy
`hoststack deploy list`	`hoststack deploy list <service-id> [--json]`	List recent deploys for a service
`hoststack deploy logs`	`hoststack deploy logs <service-id> <deploy-id> [--json]`	Print build logs for a specific deploy
`hoststack deploy cancel`	`hoststack deploy cancel <service-id> <deploy-id>`	Cancel an in-progress deploy
`hoststack deploy rollback`	`hoststack deploy rollback <service-id> <deploy-id>`	Roll back the service to a previous deploy

Environment Variables

Command	Usage	Description
`hoststack env list`	`hoststack env list <service-id>`	List variables on a service (secret values are masked)
`hoststack env set`	`hoststack env set <service-id> KEY=VALUE [--secret\|--no-secret] [--target build\|runtime\|both]`	Create or update a single variable (upsert by key). Use --secret/--no-secret to set its secret status and --target to control where it is injected.
`hoststack env get`	`hoststack env get <service-id> <KEY>`	Get a single variable (secret values are masked)
`hoststack env delete`	`hoststack env delete <service-id> <KEY\|env-var-id>`	Delete a variable by its KEY or numeric env-var id
`hoststack env bulk`	`hoststack env bulk <service-id> KEY1=VAL1 KEY2=VAL2 ... [--secret] [--target build\|runtime\|both]`	Replace ALL variables on a service with the given set (anything not listed is removed). --secret marks every variable secret; --target sets their injection target.

Databases

Command	Usage	Description
`hoststack db list`	`hoststack db list --project <project-id> [--json]`	List databases in a project
`hoststack db get`	`hoststack db get <database-id>`	Show database details
`hoststack db create`	`hoststack db create --project <project-id\|prj_…> --name my-db --engine <postgres\|redis\|mysql\|mariadb\|mongodb> [--version <v>]`	Provision a new database
`hoststack db credentials`	`hoststack db credentials <database-id>`	Show host, port, user, password, connection URL
`hoststack db connect`	`hoststack db connect <database-id>`	Open psql / mysql / mongosh / redis-cli with creds pre-filled
`hoststack db delete`	`hoststack db delete <database-id>`	Deprovision a database
`hoststack db upgrade-to-ha`	`hoststack db upgrade-to-ha <database-id>`	Migrate a standalone Postgres to a 3-node Patroni HA cluster
`hoststack db cluster`	`hoststack db cluster <database-id> [--json]`	Show HA cluster topology and failover history

Domains

Command	Usage	Description
`hoststack domains list`	`hoststack domains list [--json]`	List custom domains
`hoststack domains add`	`hoststack domains add <domain> --service <service-id\|svc_…> [--path-prefix <prefix>]`	Attach a custom domain to a service
`hoststack domains verify`	`hoststack domains verify <domain-id>`	Re-check DNS and (re)provision the Let's Encrypt cert
`hoststack domains delete`	`hoststack domains delete <domain-id>`	Remove a custom domain

Volumes

Command	Usage	Description
`hoststack volumes list`	`hoststack volumes list <service-id>`	List volumes attached to a service
`hoststack volumes create`	`hoststack volumes create <service-id> <name> <mount-path> --size <gb>`	Attach a new volume
`hoststack volumes resize`	`hoststack volumes resize <service-id> <volume-id> <new-size-gb>`	Grow a volume (cannot shrink)
`hoststack volumes delete`	`hoststack volumes delete <service-id> <volume-id>`	Detach and deprovision a volume

Environments

Command	Usage	Description
`hoststack environments list`	`hoststack environments list <project-id>`	List environments in a project
`hoststack environments create`	`hoststack environments create <project-id> --name staging --type <production\|staging\|development\|preview> [--protected]`	Create a new environment
`hoststack environments delete`	`hoststack environments delete <project-id> <environment-id>`	Delete an environment

Cron

Command	Usage	Description
`hoststack cron list`	`hoststack cron list <service-id> [--limit <n>] [--json]`	List recent cron executions for a service
`hoststack cron get`	`hoststack cron get <service-id> <execution-id> [--json]`	Show details of a single cron execution
`hoststack cron trigger`	`hoststack cron trigger <service-id>`	Trigger an ad-hoc cron run

Runtime

Command	Usage	Description
`hoststack logs`	`hoststack logs <service-id> [--lines 200] [--since 1h]`	Print recent runtime logs for a service

Infrastructure as Code

Command	Usage	Description
`hoststack init`	`hoststack init [--force]`	Generate a hoststack.yaml template in the cwd
`hoststack validate`	`hoststack validate`	Type-check a local hoststack.yaml against the schema (no API call)

Dev boxes

hoststack dev drives dev environments from your own terminal. new creates a standalone box in the team's Development area, create puts one inside a project (or clones an existing service into one), and delete removes the box, its cloned database, and its /workspace volume in one call.

bash

hoststack dev new --name app-dev --github-id 42 --db postgres,redis
hoststack dev new --repo https://github.com/you/your-app.git
hoststack dev new --name scratch                  # blank box
hoststack dev list
hoststack dev create --project prj_abc --repo https://github.com/me/app.git
hoststack dev create --service svc_abc            # clone of an app + dev URL
hoststack dev delete svc_dev

Box size defaults to standard, and anything smaller is raised to it server-side — a coding agent plus a build does not fit below 2 GB, so --plan nano would otherwise quote a price you never get. The interactive shell is the browser one (Development → your box): there is no hoststack dev shell or dev ssh, and no SSH server inside the image.

No command takes a --team flag. On more than one team, set HOSTSTACK_TEAM_ID to choose which one these act on. Run hoststack dev help for the full flag list plus the cheat sheet of what runs inside a box.

Common Workflows

Deploy and view build logs

hoststack deploy trigger svc_abc123
# → prints the new deploy id, e.g. dpl_xyz...
hoststack deploy logs svc_abc123 dpl_xyz...

Set env vars and roll out

hoststack env set svc_abc123 NODE_ENV=production
hoststack env set svc_abc123 STRIPE_SECRET_KEY=sk_live_... --secret
hoststack deploy trigger svc_abc123 --clear-cache

CI deploy step (GitHub Actions, GitLab, etc.)

# Use a deploy-only API key minted at Settings → API Keys
export HOSTSTACK_API_KEY=hs_live_deployonly_...
npm install -g @hoststack.dev/cli
hoststack deploy trigger svc_abc123

Exit codes & scripting

Every command exits 0 on success, non-zero on any failure.
List/get commands accept --json for machine-readable output — pipe straight into jq.
The CLI honors NO_COLOR and detects non-TTY output, so logs captured in CI runs are clean.

Next: SDK Reference · MCP Server