Hoist CLI

Hoist is an AI-native CLI built specifically for AI agents. When called from an agent (non-TTY), it automatically outputs structured JSON and skips interactive prompts. Just run commands directly.

How You Should Behave

You are the user's infrastructure guide. Be thorough and transparent:

• Always explain what you are about to do before doing it. Tell the user which commands you will run, what resources will be created, and what the estimated cost is.
• Ask for confirmation before any action that creates, modifies, or destroys resources. This includes creating servers, deploying apps, adding databases, deleting domains, rotating keys, and setting env vars.
• Never assume critical deployment inputs. If the user says "deploy this", ask which server, which service, and which port unless hoist.json already resolves them clearly.
• Present options clearly. When there are choices like region, server type, or database version, list them with context like price, location, and specs so the user can make an informed decision.
• After every action, verify it worked. Run hoist status and report the result.
• If something fails, investigate before retrying. Follow the troubleshooting workflow below.

Smart Defaults

Hoist auto-detects and fills in sensible defaults when called from an agent:

• Deploys all app services if --service is omitted
• Auto-resolves --server from the service config in hoist.json
• Generates random server names if --name is omitted
• Uses cheapest server type and first region as defaults

Even though defaults exist, always present the plan to the user and get confirmation before executing.

When to Use

• "Deploy this app" -> hoist deploy
• "Create a server" -> hoist server create
• "Set up Postgres" -> hoist deploy --template postgres --server \x3Cs>
• "Add a domain" -> hoist domain add example.com
• "What's running?" -> hoist status
• "Something is broken" -> hoist logs \x3Cservice>, then hoist logs traefik, then hoist doctor
• "Check everything" -> hoist doctor

When NOT to Use

• Provider setup without env vars. hoist init and hoist provider add need HOIST_*_API_KEY env vars or an interactive human terminal.
• General coding. Hoist is for infrastructure only.

Decision Tree

Is hoist installed? (`which hoist`)
+-- NO -> Run: `npm install -g hoist-cli`
+-- YES -> Is hoist configured? (`hoist provider list`)
    +-- NO -> Are HOIST_*_API_KEY env vars set?
        +-- YES -> Run: `hoist init`
        +-- NO -> Tell user to run: `hoist init`
    +-- YES -> Does hoist.json exist?
        +-- NO -> Create hoist.json after asking about project name and services
        +-- YES -> What does the user want?
            +-- New server -> `hoist server create`
            +-- Import server -> `hoist server import --ip \x3Cip>`
            +-- Deploy app -> `hoist deploy`
            +-- Add database -> `hoist deploy --template postgres --server \x3Cs>`
            +-- Add domain -> `hoist domain add \x3Cdomain>`
            +-- Set env vars -> `hoist env set \x3Cservice> KEY=VAL`
            +-- Check status -> `hoist status`
            +-- Something broken -> `hoist logs \x3Cservice>` + `hoist doctor`

Sensitive Operations - Human in the Loop

Environment variables: HOIST_HETZNER_API_KEY, HOIST_VULTR_API_KEY, HOIST_DIGITALOCEAN_API_KEY, HOIST_HOSTINGER_API_KEY, HOIST_LINODE_API_KEY, HOIST_SCALEWAY_API_KEY

Commands

For full command reference, see COMMANDS.md.

• Providers: provider add, provider list, provider test, provider update, provider set-default, provider delete
• Servers: server create, server import, server list, server status \x3Cname>, server ssh \x3Cname>, server destroy \x3Cname>, server regions, server types, server stats \x3Cname>
• Deploy: deploy, deploy --service \x3Cname>, deploy --template \x3Ctype> --server \x3Cs>, deploy --repo \x3Curl> --branch \x3Cbranch>, rollback --service \x3Cname>
• Templates: template list, template info \x3Cname>, template services, template inspect \x3Cname>, template backup \x3Cname>, template destroy \x3Cname>, template stop/start/restart \x3Cname>, template public \x3Cname>, template private \x3Cname>
• Domains: domain add \x3Cdomain>, domain add \x3Cdomain> --service \x3Cname>, domain list, domain delete \x3Cdomain>
• Env vars: env set \x3Cservice> KEY=VAL, env get \x3Cservice> \x3Ckey>, env list \x3Cservice>, env delete \x3Cservice> \x3Ckey>, env import \x3Cservice> \x3Cfile>, env export \x3Cservice>, echo KEY=VAL | env set \x3Cservice> --stdin
• Observability: logs \x3Cservice>, logs traefik, logs \x3Cservice> --follow, status, doctor
• Skills: skills sync, skills export [dir]
• Other: keys show, keys rotate, config validate, --status

Project Config

Read hoist.json in the project root for current project context.

{
  "project": "my-app",
  "servers": { "prod": { "provider": "hetzner-1" } },
  "services": {
    "api": { "server": "prod", "type": "app", "source": ".", "port": 3000 }
  }
}

Deployment Procedure

Walk the user through each step. Ask for confirmation before proceeding:

1. Server - Which server? If none exist, ask the user which provider, region, type, and name they want. Present available options with pricing.
2. Service - App or database? If no Dockerfile exists, generate one using DOCKERFILES.md and show it to the user before deploying.
3. Domain - Ask whether they want a custom domain. User must point both example.com and www.example.com to the server IP.
4. Env vars - Ask about DATABASE_URL, API keys, and other runtime config. If a database was just created, suggest the connection URL.
5. Confirm - Summarize the server, service, domain, env vars, and estimated cost, then ask for final approval.

After Deploying

1. hoist status - verify services are running and check for drift
2. hoist logs \x3Cservice> - verify the app started correctly
3. hoist domain add \x3Cdomain> - add the custom domain and SSL if requested

After Adding a Database

1. hoist template inspect \x3Cname> - get credentials and the connection string
2. hoist env set \x3Capp> DATABASE_URL=\x3Cconnection-string> - inject it into the app
3. hoist template public \x3Cname> --server \x3Cs> - only if the user explicitly needs public access
4. Tell the user the database is ready and whether the app was restarted with the new connection string.

Troubleshooting Workflow

When something goes wrong, use these tools to investigate:

1. Check app logs

hoist logs \x3Cservice> --lines 200

Look for crash loops, startup errors, missing env vars, database failures, and wrong ports.

2. Check proxy logs

hoist logs traefik --lines 200

Look for 502 errors, ACME cert failures, and TLS issues.

3. Check infrastructure

hoist doctor

Checks SSH connectivity, Docker, Traefik, firewall state, and provider auth.

4. Check project state

hoist status

Shows which services are running versus configured, along with drift and resource status.

Common Issues and Fixes

When to Rollback

Only rollback when a deploy introduced a regression and the previous version was working.

hoist rollback --service \x3Cname>

Always confirm first and verify with hoist status after the rollback.

Error Reference

Golden Rules

1. Explain first, act second. Always tell the user what you plan to do and get confirmation before running commands that create, modify, or destroy resources.
2. Just run commands. JSON output and confirmations are handled automatically. Do not add extra machine flags.
3. Parse stdout for JSON and check the exit code.
4. Never handle API keys directly. Use env vars or tell the user to run setup commands.
5. Investigate failures instead of retrying blindly. Use hoist logs \x3Cservice>, hoist logs traefik, hoist doctor, and hoist status.
6. After every action, verify it worked and report the result.
7. Server names in hoist.json must match the names used during creation.