deployhq-cli: Instructions file for Claude Code

CLAUDE.md

What is this?

deployhq-cli is the official DeployHQ command-line interface — a Go binary that wraps the DeployHQ REST API. Designed for both humans and AI agents.

Development

go build ./cmd/dhq/        # binary outputs as dhq       # Build binary
go test ./... -v               # Run all tests (96 tests)
go vet ./...                   # Static analysis

Architecture

pkg/sdk/           Public Go SDK (97 methods, zero internal/ imports)
                    Clean boundary — extractable to standalone module later.

internal/output/    Wrangler-pattern output engine
                    stderr=human messages, stdout=data (table or JSON)
                    --json <fields> for field selection
                    DEPLOYHQ_OUTPUT_FILE for JSONL capture

internal/config/    4-layer Viper config
                    flags > env vars > .deployhq.toml > ~/.deployhq/config.toml

internal/auth/      Keyring + file fallback credential storage

internal/harness/   Agent detection (DEPLOYHQ_AGENT, CLAUDE_CODE, CI)

internal/cli/       Command execution pipeline, lazy SDK client

internal/commands/  All CLI commands (42 top-level, 155+ total)

internal/version/   Update checker (GitHub releases API)

internal/skillinstaller/  Detects installed AI agents (12 supported) and
                    installs the DeployHQ skill into each one's native format.
                    user-scope targets write to $HOME; project-scope targets
                    write into the repo (opt-in via --agent). Powers
                    `dhq skills` and the `dhq hello` onboarding step.

skills/deployhq/    Agent skill guide + per-domain reference docs (9 files)
                    SKILL.md is the entry point for any AI agent.

skill-evals/deployhq/  Eval suite (69 cases) testing LLM → CLI translation
                        run-evals.sh drives Claude API, checks command accuracy.

Key Design Decisions

• Output contract: stdout is ALWAYS data (table or JSON), stderr is ALWAYS human text. Never mixed.
• --json <fields>: Field selection on any command. Piped output auto-switches to JSON.
• FlexString type: The DeployHQ API inconsistently returns some fields as strings or numbers. FlexString handles both.
• dhq api: Escape hatch covering all 144+ endpoints not in the command tree.
• Breadcrumbs: JSON responses include suggested next commands with resource type and id.
• --non-interactive: Strict mode that never prompts. Auto-enabled for detected agents and piped output. Ambiguous inputs fail with structured errors listing available options.
• Agent metadata: dhq commands --json includes per-command agent object with interactive, destructive, idempotent, safe_for_automation, resource_types. Defined in internal/commands/agent_metadata.go.
• Structured errors: Error responses include exit_code, retryable, and recovery actions.
• No login in CI: DEPLOYHQ_ACCOUNT + DEPLOYHQ_EMAIL + DEPLOYHQ_API_KEY env vars.
• Pagination: --page and --per-page on paginated list commands (deployments, servers, server-groups). JSON output includes pagination metadata when available. Non-paginated endpoints don't have these flags.
• Dry-run: dhq deploy --dry-run creates a preview deployment without executing. Returns preview_pending status. Mutually exclusive with --wait.
• API spec: https://api.deployhq.com/docs (OpenAPI 3.1.0, machine-readable JSON at /docs.json)