DeployHQ CLI — Agent Skill Guide

DeployHQ CLI — Agent Skill Guide

Identity

DeployHQ is a deployment automation platform. The dhq CLI (binary name: deployhq) manages projects, servers, deployments, and infrastructure via the DeployHQ REST API. Designed for both humans and AI agents.

Authentication

Three methods (checked in order):

1. Environment variables (CI/​agents): DEPLOYHQ_ACCOUNT + DEPLOYHQ_EMAIL + DEPLOYHQ_API_KEY
2. Config files: ~/​.deployhq/​config.toml or .deployhq.toml in project directory
3. Interactive login: dhq auth login

Verify with: dhq auth status

Output Contract

Critical rule: stdout is ALWAYS data (table or JSON). stderr is ALWAYS human messages.

• TTY mode: Table output with headers
• Piped/​non-TTY: Auto-switches to JSON
• --json: Force JSON output. Optionally select fields: --json name,status,identifier
• Breadcrumbs: JSON responses include breadcrumbs array with suggested next commands
• Exit codes: 0 = success, non-zero = failure

Non-Interactive Mode

Use --non-interactive to guarantee the CLI never prompts. This mode is auto-enabled when an agent is detected or output is piped.

In non-interactive mode, any ambiguity (e.g. multiple servers, missing required values) fails with a structured error listing available options instead of prompting.

The only commands that cannot run non-interactively are: dhq init, dhq hello, dhq configure (use their flag-based alternatives instead).

Command Groups

Decision Trees

"Deploy code"

1. dhq projects list --json — find project permalink
2. dhq servers list -p <project> --json — find server identifier
3. dhq deploy -p <project> -s <server> --json — create deployment
4. dhq deployments watch <id> -p <project> — monitor progress

"Check what's deployed"

1. dhq deployments list -p <project> --json — recent deployments
2. dhq deployments show <id> -p <project> --json — details + steps

"Something went wrong"

1. dhq deployments logs <id> -p <project> — read step logs
2. dhq rollback <id> -p <project> --json — rollback if needed
3. dhq deployments abort <id> -p <project> — abort if running

"Set up a new project"

1. dhq projects create --name "My App" --json — create project
2. dhq repos create -p <project> --scm-type git --url <repo-url> --json — connect repo
3. dhq servers create -p <project> --name Production --protocol-type ssh --hostname <host> --username <user> --json — add server
4. dhq deploy -p <project> --json — first deployment

"Configure deployment"

1. dhq env-vars create -p <project> --name KEY --value val — add env var
2. dhq config-files create -p <project> --path .env --body "..." --json — add config file
3. dhq excluded-files create -p <project> --pattern "node_modules" --json — add exclusion
4. dhq build-commands create -p <project> --name "Install" --command "npm install" --json — add build step
5. dhq deployment-checks create -p <project> --name "Health" --stage post_deploy --check-type http --http-url https://app.example.com/health --http-expected-status 200 --json — gate the deploy

"Escape hatch (any API endpoint)"

dhq api GET /​projects
dhq api GET /​projects/<permalink>/​deployments
dhq api POST /​projects/<permalink>/​deployments --body '{"deployment":{...}}'

Invariants

• Always use --json for machine-readable output when scripting or in agent context
• Use --non-interactive to guarantee no prompts (auto-enabled for agents and piped output)
• JSON responses include breadcrumbs with action and cmd fields; deploy commands also include resource and id
• Error responses include retryable, exit_code, and recovery actions when applicable
• Exit codes: 0 = success, 1 = user error, 2 = internal, 3 = auth, 4 = network, 5 = not found, 6 = conflict
• Empty results return exit 0 with empty data array (not an error)
• dhq commands --json includes per-command agent metadata: interactive, destructive, idempotent, safe_for_automation, resource_types
• dhq api covers all 144+ API endpoints not in the command tree
• Project flag (-p/--project) accepts permalink or identifier
• Server flag (-s/--server) uses fuzzy matching: exact > normalized > substring
• Config precedence: flags > env vars > .deployhq.toml > ~/​.deployhq/​config.toml

Gotchas

• Some API fields return strings OR numbers inconsistently (handled internally by FlexString)
• dhq deploy auto-fetches latest revision if --revision is omitted
• dhq deploy is incremental by default — it picks up from the server's last successful deploy. Use --full for a full-branch deploy or --start-revision <sha> to pin a specific start commit
• dhq deploy --wait blocks until deployment completes (use --timeout to cap)
• Deployment watch uses TUI in TTY mode, append-only in pipes
• dhq env-vars create prompts for value if --value is omitted (not agent-friendly — always pass --value)

Triggers

• User mentions "deploy", "deployment", "release", "ship" → deployment workflow
• User mentions "server", "hosting", "target" → server management
• User mentions "rollback", "revert", "undo" → rollback workflow
• User mentions "environment variable", "env var", "config", "secret" → configuration
• User mentions "branch", "commit", "repository" → repo management
• User mentions "DeployHQ", "deployhq", "dhq" → general CLI usage