CLI Reference
Complete reference for the Hostess command-line interface — your primary tool for deploying, managing, and monitoring applications on the Hostess platform.
Overview
The Hostess CLI is your primary interface for deploying and managing applications on the Hostess platform. It handles everything from deploying your stack with a single command, to managing secrets, viewing logs, and connecting to databases.
hostess deployThe CLI is designed around the philosophy of Docker Compose for Production — define your services in hostess.yml, run one command, and your entire stack is live.
Installation
curl -fsSL https://hostess.sh/install.sh | shAfter installation, authenticate with your Hostess account:
hostess loginCommon Targeting Flags
Many project-scoped commands use the same targeting flags:
| Flag | Short | Type | Description |
|---|---|---|---|
--project | Varies by command | string | Project name or slug. Deployment-scoped commands commonly provide -p; secrets commands use --project only. |
--env | Varies by command | string | Environment name (e.g., production, staging). Deployment-scoped commands commonly provide -e; deploy and domains add use --env only. |
Commands that accept --token use it with highest priority, followed by HOSTESS_TOKEN, then the token saved by hostess login. Check each command reference page for its exact flags.
Authentication Resolution
For commands that accept --token, authentication is resolved in this order:
--tokenflag — Highest priority. Use this in CI/CD pipelines.HOSTESS_TOKENenvironment variable — Useful for setting a default token in your shell profile or CI environment.- Saved token — From
hostess login. Stored in~/.hostess/config.json.
# CI/CD — pass token explicitly
hostess deploy --token $HOSTESS_TOKEN
# Or set as environment variable
export HOSTESS_TOKEN="pat_abc123..."
hostess deployProject and Environment Resolution
When a project-scoped command needs a project, the CLI resolves it in this order:
Project name:
--project/-pflagnamefield inhostess.ymlin the current directory
Environment targeting depends on the command:
hostess deployandhostess domains adduse--envwhen provided and choose an environment automatically when omitted.- Deployment-scoped commands such as
hostess inspect,hostess ps,hostess logs,hostess connect, andhostess backupsuse the latest deployment when--envis omitted. Pass--envto select the latest deployment in that environment. hostess jobs runrequires--envbecause manual job triggers target an environment directly.
Command Aliases
For faster workflow, several common subcommands have top-level aliases:
| Alias | Full Command | Description |
|---|---|---|
hostess ls | hostess deployments list | List deployments |
hostess list | hostess deployments list | List deployments |
hostess inspect | hostess deployments inspect | Inspect a deployment |
hostess rm | hostess deployments remove | Remove a deployment |
hostess delete | hostess deployments remove | Remove a deployment |
hostess ps | hostess services list | List services |
hostess logs | hostess services logs | Stream service logs |
Some grouped commands also include shorter nested aliases:
| Alias | Full Command | Description |
|---|---|---|
hostess dep | hostess deployments | Deployment command group |
hostess deployments ls | hostess deployments list | List deployments |
hostess deployments rm | hostess deployments remove | Remove a deployment |
hostess deployments delete | hostess deployments remove | Remove a deployment |
hostess services ls | hostess services list | List services |
hostess jobs ls | hostess jobs list | List jobs |
# These are equivalent:
hostess deployments list
hostess ls
# These are equivalent:
hostess services logs api --follow
hostess logs api --followCommands
Core Commands
deploy
Deploy your services to the Hostess platform.
init
Convert a docker-compose.yml to hostess.yml.
validate
Validate your hostess.yml configuration locally.
update
Upgrade the Hostess CLI with the official install script.
Account Commands
Deployment Management
deployments
List, inspect, and remove deployments.
services
List services and stream logs.
connect
Open local tunnels or shells for service instances.
backups
Create, restore, and manage service backups.
jobs
List, inspect, trigger, and reset top-level jobs.