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_…> [--machine <name\|id>]`	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>] [--machine <name\|id>]`	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] [--machine <name\|id>] [--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>] [--plan <micro\|starter\|standard\|pro>] [--machine <name\|id>]`	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 external`	`hoststack db external <database-id> --enable [--allow <cidr> ...] \| --disable`	Toggle external (public) access. Postgres only, TLS enforced, and --allow narrows it to specific CIDRs.
`hoststack db delete`	`hoststack db delete <database-id>`	Deprovision a database
`hoststack db suspend`	`hoststack db suspend <database-id>`	Stop the container and keep the data
`hoststack db resume`	`hoststack db resume <database-id>`	Restart a suspended database
`hoststack db link`	`hoststack db link <database-id> --service <service-id\|svc_…> [--alias <PREFIX>]`	Attach the database to a service, so its connection URL is injected as DATABASE_URL / REDIS_URL / MONGO_URL. --alias prefixes them when a service links more than one. Takes effect on the NEXT deploy.
`hoststack db links`	`hoststack db links --service <service-id\|svc_…>`	List the managed resources linked to a service
`hoststack db unlink`	`hoststack db unlink --service <service-id\|svc_…> --link <link-id>`	Remove a link (the injected variables go on the next deploy)
`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

Own hardware

Command	Usage	Description
`hoststack machines list`	`hoststack machines list [--json]`	List enrolled machines, whether they are online, and what runs on each (alias: ls)
`hoststack machines show`	`hoststack machines show <name\|machine-id> [--json]`	One machine and everything currently running on it — worth reading before switching it off, because that list is what goes away with it (alias: get)
`hoststack machines add`	`hoststack machines add <name>`	Register a machine and print the installer to run on it, carrying a single-use pairing token. Run that line on the machine itself, not here (aliases: create, enrol, enroll)
`hoststack machines remove`	`hoststack machines remove <name\|machine-id>`	Unenrol a machine and print how to clean the agent off it. Refused while anything is still pinned to it (aliases: rm, delete)

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

Errors

Command	Usage	Description
`hoststack errors list`	`hoststack errors list [--service <id>] [--status <s>] [--sort count] [--json]`	Exceptions your apps reported, grouped by cause
`hoststack errors show`	`hoststack errors show <issue-id> [--json]`	One issue plus the stack traces behind it
`hoststack errors resolve`	`hoststack errors resolve <issue-id>`	Mark fixed — you are told if it comes back
`hoststack errors ignore`	`hoststack errors ignore <issue-id>`	Keep counting it, stop being told about it
`hoststack errors fix`	`hoststack errors fix <issue-id> [--box <service-id>]`	Write an agent task for this error in the project's dev box
`hoststack errors keys`	`hoststack errors keys <list\|new\|rm> <service-id> [...]`	Mint, list and revoke the write-only ingest key your app reports with

Analytics

Command	Usage	Description
`hoststack analytics sites`	`hoststack analytics sites [--json]`	Every site this team tracks, with its key and retention
`hoststack analytics add`	`hoststack analytics add <domain> [--name <name>]`	Start tracking a domain — hosted here or anywhere else
`hoststack analytics check`	`hoststack analytics check <domain> [--json]`	Is a site reporting, and if not, which of the five reasons is it
`hoststack analytics stats`	`hoststack analytics stats [domain] [--range 24h\|7d\|30d\|90d\|12mo] [--json]`	Traffic for one site, or every site side by side
`hoststack analytics snippet`	`hoststack analytics snippet <domain>`	The script tag to paste into a site’s <head>
`hoststack analytics rotate`	`hoststack analytics rotate <domain>`	Issue a new site key; the old one keeps working for 30 days
`hoststack analytics rm`	`hoststack analytics rm <domain>`	Delete a site and every event recorded for it

Uptime

Command	Usage	Description
`hoststack uptime get`	`hoststack uptime get <service-id> [--json]`	Show the check on a service's public URL and its last result
`hoststack uptime set`	`hoststack uptime set <service-id> [--path /healthz] [--every 60] [--after 3]`	Create or update the check (editing it resets its recorded state)
`hoststack uptime disable`	`hoststack uptime disable <service-id>`	Keep the configuration, stop probing
`hoststack uptime rm`	`hoststack uptime rm <service-id>`	Delete the check

GitHub

Command	Usage	Description
`hoststack github sync`	`hoststack github sync`	Re-sync repositories from the connected GitHub installation(s). Run it after pushing a new repo so HostStack can see it.

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

Attach a managed database to a service

hoststack db create --project prj_abc --name app-db --engine postgres
hoststack db link db_abc --service svc_xyz   # injects DATABASE_URL
hoststack deploy trigger svc_xyz             # the link lands on the next deploy

Run a service on your own machine

hoststack machines add desktop
# → prints a one-line installer; run THAT on the machine, as root
hoststack machines list
hoststack services create --name api --type web --project prj_abc --machine desktop

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