## Getting Started (read this first)

This skill drives the **DeployHQ CLI** (`dhq`). If `dhq` is not already installed and authenticated, do this before running any command below.

### 1. Install the CLI

A single binary, no runtime dependencies (macOS, Linux, Windows).

```bash
# macOS / Linux (Homebrew)
brew install deployhq/tap/dhq

# macOS / Linux (script)
curl -fsSL https://deployhq.com/install/cli | sh
```

Windows (Scoop):

```powershell
scoop bucket add deployhq https://github.com/deployhq/scoop-bucket
scoop install dhq
```

Verify with `dhq --version` and `dhq doctor`.

### 2. Authenticate

Interactive (stores credentials in the OS keyring):

```bash
dhq auth login
```

For CI or agent contexts, set environment variables instead — no login needed:

```bash
export DEPLOYHQ_ACCOUNT=mycompany      # your account subdomain
export DEPLOYHQ_EMAIL=you@example.com
export DEPLOYHQ_API_KEY=your-api-key   # DeployHQ web UI → Settings → API Keys
```

Confirm with `dhq auth status`.

### 3. Deploy

```bash
dhq deploy -p my-app -s production --wait
```

Once `dhq` is installed and authenticated, use the command groups and decision trees below.

# 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

| Group | Description | Reference |
|-------|-------------|-----------|
| **projects** | Create, list, update, delete projects | [projects.md](#ref-projects) |
| **servers** | Manage deployment targets (SSH, FTP, S3, etc.) | [servers.md](#ref-servers) |
| **deployments** | Create, monitor, rollback deployments | [deployments.md](#ref-deployments) |
| **repos** | Repository configuration, branches, commits | [repos.md](#ref-repos) |
| **configuration** | Env vars, config files, build commands, exclusions, deployment checks, cache files, build languages, known hosts | [configuration.md](#ref-configuration) |
| **global resources** | Global servers, env vars, config files, SSH keys, templates | [global-resources.md](#ref-global-resources) |
| **operations** | Activity, status, test-access, doctor | [operations.md](#ref-operations) |
| **auth & setup** | Authentication, CLI config, agent setup | [auth-setup.md](#ref-auth-setup) |

## 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)"
```bash
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

## Reference Detail

The sections below inline the per-group reference docs so this file is self-contained.

<a id="ref-projects"></a>

### Projects

## Projects Reference

### Commands

#### `dhq projects list`
List all projects. Starred projects appear first.

```bash
dhq projects list --json
dhq projects list --json name,permalink,last_deployed_at
```

#### `dhq projects show [permalink]`
Show project details including servers. Uses `--project` or positional arg.

```bash
dhq projects show my-app --json
dhq projects show -p my-app --json
```

#### `dhq projects create`
Create a new project.

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Project name |
| `--zone` | no | Deployment zone (see `dhq zones list`) |
| `--template` | no | Template identifier |

```bash
dhq projects create --name "My App" --json
dhq projects create --name "My App" --zone us-east --json
```

#### `dhq projects update [permalink]`
Update project settings.

| Flag | Description |
|------|-------------|
| `--name` | New project name |
| `--permalink` | New permalink |
| `--zone` | Deployment zone |
| `--email-notify-on` | Email notification trigger |
| `--notification-email` | Notification email address |
| `--notify-pusher` | Notify code pusher |
| `--check-undeployed-changes` | Check for undeployed changes |
| `--store-artifacts` | Store deployment artifacts |

```bash
dhq projects update my-app --name "My Application" --json
```

#### `dhq projects delete [permalink]`
Delete a project. Irreversible.

```bash
dhq projects delete my-app
```

#### `dhq projects star [permalink]`
Toggle starred/favourite status.

Aliases: `fav`, `unfav`, `favourite`, `unfavourite`

```bash
dhq projects star my-app --json
```

#### `dhq projects insights [permalink]`
Show project deployment insights. JSON only.

```bash
dhq projects insights my-app --json
```

#### `dhq projects upload-key [permalink]`
Upload custom SSH public key.

```bash
dhq projects upload-key my-app --key-file ~/.ssh/id_rsa.pub --json
```

#### `dhq projects badge [permalink]`
Get deployment status badge URL (SVG).

```bash
dhq projects badge my-app
```

<a id="ref-servers"></a>

### Servers

## Servers Reference

### Commands

#### `dhq servers list`
List servers in project.

```bash
dhq servers list -p my-app --json
dhq servers list -p my-app --json name,identifier,protocol_type
```

#### `dhq servers show <identifier>`
Show server details.

```bash
dhq servers show srv-001 -p my-app --json
```

#### `dhq servers create`
Create a server. Flags vary by protocol type.

**Common flags (all protocols):**

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Server name |
| `--protocol-type` | yes | One of: ssh, ftp, ftps, rsync, s3, s3_compatible, digitalocean, hetzner_cloud, heroku, netlify, shopify |
| `--path` | no | Deployment path |
| `--environment` | no | Environment label |

**SSH/FTP/FTPS/Rsync flags:**

| Flag | Description |
|------|-------------|
| `--hostname` | Server hostname |
| `--username` | Login username |
| `--password` | Login password |
| `--port` | Connection port |
| `--use-ssh-keys` | Use SSH key auth |
| `--install-key` | Auto-install deploy key |

**S3/S3-Compatible flags:**

| Flag | Description |
|------|-------------|
| `--bucket-name` | S3 bucket name |
| `--access-key-id` | AWS access key |
| `--secret-access-key` | AWS secret key |
| `--custom-endpoint` | Custom S3 endpoint (for S3-compatible) |

**Cloud provider flags:**

| Flag | Provider | Description |
|------|----------|-------------|
| `--personal-access-token` | DigitalOcean | DO API token |
| `--droplet-name` | DigitalOcean | Target droplet |
| `--api-token` | Hetzner Cloud | Hetzner API token |
| `--hetzner-server-name` | Hetzner Cloud | Target server |
| `--app-name` | Heroku | Heroku app name |
| `--api-key` | Heroku | Heroku API key |
| `--site-id` | Netlify | Netlify site ID |
| `--access-token` | Netlify/Shopify | Provider access token |
| `--store-url` | Shopify | Store URL |
| `--theme-name` | Shopify | Theme name |

**Examples:**

```bash
## SSH server
dhq servers create -p my-app --name Production --protocol-type ssh \
  --hostname example.com --username deploy --use-ssh-keys --json

## S3 bucket
dhq servers create -p my-app --name "Static Assets" --protocol-type s3 \
  --bucket-name my-bucket --access-key-id AKIA... --secret-access-key ... --json

## Netlify
dhq servers create -p my-app --name Netlify --protocol-type netlify \
  --site-id abc123 --access-token ... --json
```

#### `dhq servers update <identifier>`
Update server settings.

```bash
dhq servers update srv-001 -p my-app --name "Production v2" --json
```

#### `dhq servers delete <identifier>`
Delete a server.

```bash
dhq servers delete srv-001 -p my-app
```

#### `dhq servers reset-host-key <identifier>`
Reset SSH host key verification.

```bash
dhq servers reset-host-key srv-001 -p my-app
```

### Server Groups

#### `dhq server-groups list`
```bash
dhq server-groups list -p my-app --json
```

#### `dhq server-groups create`
```bash
dhq server-groups create -p my-app --name "US Servers" --json
```

#### `dhq server-groups update <identifier>`
```bash
dhq server-groups update grp-001 -p my-app --name "EU Servers" --json
```

#### `dhq server-groups delete <identifier>`
```bash
dhq server-groups delete grp-001 -p my-app
```

### Server Name Resolution

When using `--server` / `-s` with `dhq deploy`, names are resolved:
1. Exact case-insensitive match
2. Normalized match (stripped non-alphanumeric)
3. Substring match
4. Interactive picker (TTY) or error (non-TTY)

<a id="ref-deployments"></a>

### Deployments

## Deployments Reference

### Commands

#### `dhq deploy`
Shortcut for creating a deployment with smart defaults.

| Flag | Short | Description |
|------|-------|-------------|
| `--branch` | `-b` | Branch to deploy |
| `--server` | `-s` | Server or group identifier (fuzzy matched) |
| `--revision` | `-r` | End revision SHA (auto-fetches latest if omitted) |
| `--start-revision` | | Start revision SHA (default: server's last deployed commit) |
| `--full` | | Deploy entire branch from the first commit (overrides incremental default) |
| `--wait` | `-w` | Block until deployment completes |
| `--timeout` | | Timeout in seconds for `--wait` (0 = no timeout) |

```bash
## Basic deploy (incremental — only changes since the server's last deploy)
dhq deploy -p my-app --json

## Deploy specific branch to specific server
dhq deploy -p my-app -b staging -s "Staging Server" --json

## Deploy and wait for completion
dhq deploy -p my-app -s Production --wait --json

## Deploy with timeout
dhq deploy -p my-app --wait --timeout 300 --json

## Deploy a specific commit range (e.g. a hotfix)
dhq deploy -p my-app --start-revision a1b2c3d --revision e4f5g6h --json

## Force a full deploy (entire branch from the first commit)
dhq deploy -p my-app --full --json
```

**Behaviors:**
- Auto-selects sole server; prompts for multiple (TTY) or errors (non-TTY)
- Branch resolution: `--branch` overrides everything. Otherwise deploys the **server's default branch** (`preferred_branch`). Falls back to the repo default only if the server has no preferred branch.
- Revision resolution: `--revision` overrides everything. Otherwise uses the tip SHA of the resolved branch.
- **Start revision resolution (incremental by default):** `--full` forces an empty start (full-branch deploy). Otherwise `--start-revision` is used if set. Otherwise the resolved server's `last_revision` (last successful deploy) is used — this is what makes deploys incremental. Servers with no prior deploy and server-group identifiers fall through to a full deploy because there's no single baseline to start from.
- An unknown `--branch` errors out instead of silently deploying the wrong branch.
- `--full` and `--start-revision` are mutually exclusive.
- `--wait` shows TUI progress in TTY, append-only in pipes

#### `dhq deployments list`
List recent deployments with pagination.

```bash
dhq deployments list -p my-app --json
dhq deployments list -p my-app --json identifier,status,branch,created_at
```

#### `dhq deployments show <identifier>`
Show deployment details including steps.

```bash
dhq deployments show abc123 -p my-app --json
```

#### `dhq deployments create`
Full deployment creation with all options.

| Flag | Description |
|------|-------------|
| `--branch` | Branch to deploy |
| `--revision` | End revision SHA |
| `--server` | Target server |
| `--parent` | Parent revision SHA |
| `--copy-config` | Copy config files from previous deployment |
| `--run-build` | Execute build commands |
| `--use-cache` | Use build cache |

```bash
dhq deployments create -p my-app --branch main --server Production --json
```

#### `dhq deployments abort <identifier>`
Abort a running deployment.

```bash
dhq deployments abort abc123 -p my-app --json
```

#### `dhq deployments retry <identifier>`
Retry a failed or completed deployment.

```bash
dhq deployments retry abc123 -p my-app --json
```

#### `dhq deployments rollback <identifier>`
Rollback a deployment.

```bash
dhq deployments rollback abc123 -p my-app --json
```

Shortcut: `dhq rollback <identifier> -p <project> --json`

#### `dhq deployments logs <deployment-id>`
Show deployment step logs.

| Flag | Description |
|------|-------------|
| `--step` | Specific step number (shows all if omitted) |

```bash
dhq deployments logs abc123 -p my-app
dhq deployments logs abc123 -p my-app --step 2
```

#### `dhq deployments watch <deployment-id>`
Watch deployment progress in real-time.

```bash
dhq deployments watch abc123 -p my-app
```

**Behaviors:**
- TTY: Full TUI with step-by-step progress and emoji status
- Non-TTY: Append-only output for CI/log capture
- Auto-shows logs for failed steps

### Shortcuts

| Command | Equivalent |
|---------|------------|
| `dhq deploy ...` | `dhq deployments create ...` (with smart defaults) |
| `dhq retry <id>` | `dhq deployments retry <id>` |
| `dhq rollback <id>` | `dhq deployments rollback <id>` |

### Deployment Statuses

| Status | Meaning |
|--------|---------|
| `pending` | Queued, waiting to start |
| `running` | In progress |
| `completed` | Finished successfully |
| `failed` | Finished with errors |
| `cancelled` | Aborted by user |

<a id="ref-repos"></a>

### Repos

## Repository Reference

### Commands

#### `dhq repos show`
Show repository configuration for a project.

```bash
dhq repos show -p my-app --json
```

Returns: SCM type, URL, branch, cached status.

#### `dhq repos create`
Connect a repository to a project.

| Flag | Required | Description |
|------|----------|-------------|
| `--scm-type` | yes | One of: git, mercurial, subversion |
| `--url` | yes | Repository URL |
| `--branch` | no | Default branch |

```bash
dhq repos create -p my-app --scm-type git --url git@github.com:org/repo.git --json
dhq repos create -p my-app --scm-type git --url git@github.com:org/repo.git --branch main --json
```

**Note:** After creation, the response includes a deploy key that must be added to your Git provider.

#### `dhq repos update`
Update repository configuration.

```bash
dhq repos update -p my-app --branch main --json
dhq repos update -p my-app --url git@github.com:org/new-repo.git --json
```

#### `dhq repos branches`
List repository branches with commit counts.

```bash
dhq repos branches -p my-app --json
```

#### `dhq repos commits`
List commits in a branch.

| Flag | Description |
|------|-------------|
| `--branch` | Branch name (default: project default branch) |
| `--limit` | Max commits to return |

```bash
dhq repos commits -p my-app --json
dhq repos commits -p my-app --branch develop --limit 10 --json
```

#### `dhq repos commit-info <sha>`
Show details for a single commit.

```bash
dhq repos commit-info abc123def -p my-app --json
```

#### `dhq repos latest-revision`
Get the latest revision SHA for the default branch.

```bash
dhq repos latest-revision -p my-app --json
```

<a id="ref-configuration"></a>

### Configuration

## Configuration Reference

Project-level configuration: environment variables, config files, build commands, and exclusions.

### Environment Variables

#### `dhq env-vars list`
List environment variables (values are masked).

```bash
dhq env-vars list -p my-app --json
```

#### `dhq env-vars create`
Create an environment variable.

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Variable name |
| `--value` | no | Variable value (prompts if omitted — not agent-friendly) |
| `--locked` | no | Lock variable (hides value after creation) |

```bash
dhq env-vars create -p my-app --name DATABASE_URL --value "postgres://..." --json
dhq env-vars create -p my-app --name SECRET_KEY --value "abc123" --locked --json
```

**Agent note:** Always pass `--value` explicitly. Omitting it triggers an interactive prompt.

#### `dhq env-vars update <id>`
```bash
dhq env-vars update 12345 -p my-app --value "new-value" --json
```

#### `dhq env-vars delete <id>`
```bash
dhq env-vars delete 12345 -p my-app
```

### Config Files

#### `dhq config-files list`
```bash
dhq config-files list -p my-app --json
```

#### `dhq config-files show <id>`
Show file path and content.

```bash
dhq config-files show 12345 -p my-app --json
```

#### `dhq config-files create`

| Flag | Required | Description |
|------|----------|-------------|
| `--path` | yes | File path on server |
| `--body` | yes | File content |
| `--description` | no | Description |

```bash
dhq config-files create -p my-app --path ".env" --body "APP_ENV=production" --json
```

#### `dhq config-files update <id>`
```bash
dhq config-files update 12345 -p my-app --body "APP_ENV=staging" --json
```

#### `dhq config-files delete <id>`
```bash
dhq config-files delete 12345 -p my-app
```

### Build Commands

#### `dhq build-commands list`
```bash
dhq build-commands list -p my-app --json
```

#### `dhq build-commands create`

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Command name |
| `--command` | yes | Shell command to execute |
| `--description` | no | Description |

```bash
dhq build-commands create -p my-app --name "Install" --command "npm install" --json
dhq build-commands create -p my-app --name "Build" --command "npm run build" --json
```

#### `dhq build-commands update <id>`
```bash
dhq build-commands update 12345 -p my-app --name "Install deps" --command "npm ci" --json
```

### Build Configs

#### `dhq build-configs list`
```bash
dhq build-configs list -p my-app --json
```

#### `dhq build-configs create`

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Config name |
| `--commands` | yes | Comma-separated command IDs |
| `--description` | no | Description |

```bash
dhq build-configs create -p my-app --name "Node Build" --commands "123,456" --json
```

### Excluded Files

#### `dhq excluded-files list`
```bash
dhq excluded-files list -p my-app --json
```

#### `dhq excluded-files create`

| Flag | Required | Description |
|------|----------|-------------|
| `--pattern` | yes | File/directory pattern to exclude |
| `--description` | no | Description |

```bash
dhq excluded-files create -p my-app --pattern "node_modules" --json
dhq excluded-files create -p my-app --pattern ".git" --json
dhq excluded-files create -p my-app --pattern "*.log" --json
```

### SSH Commands

#### `dhq ssh-commands list`
```bash
dhq ssh-commands list -p my-app --json
```

#### `dhq ssh-commands create`

| Flag | Required | Description |
|------|----------|-------------|
| `--command` | yes | SSH command to execute |
| `--description` | no | Description shown in the UI |
| `--timing` | no | When the command runs: `all` (default), `first`, or `after_first` |

```bash
dhq ssh-commands create -p my-app --command "sudo systemctl restart app" --description "Restart" --json
```

#### `dhq ssh-commands update <id>`

Update fields on an existing SSH command. Only flags you pass are sent — omit `--timing` to leave the current value untouched.

| Flag | Required | Description |
|------|----------|-------------|
| `--command` | no | New SSH command to execute |
| `--description` | no | New description |
| `--timing` | no | New timing: `all`, `first`, or `after_first` |

```bash
dhq ssh-commands update cmd_abc123 -p my-app --command "sudo systemctl reload app" --json
```

### Deployment Checks

Gate a deployment at a stage. A check has a `stage` (`pre_build` or `post_deploy`) and a `check_type`:
- `ssh` — runs a command over SSH on selected servers
- `http` — sends an HTTP request from the deployment worker
- `vulnerability_scan` — runs a security scanner on the build server (pre_build only)

#### `dhq deployment-checks list`
```bash
dhq deployment-checks list -p my-app --json
```

#### `dhq deployment-checks show <id>`
```bash
dhq deployment-checks show chk_abc123 -p my-app --json
```

#### `dhq deployment-checks create`

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Display name |
| `--stage` | yes | `pre_build` or `post_deploy` |
| `--check-type` | yes | `ssh`, `http`, or `vulnerability_scan` |
| `--enabled` | no | Whether the check runs (default `true`) |
| `--timeout` | no | Timeout in seconds |
| `--description` | no | Description |
| `--command` | ssh | Command to run on the target servers |
| `--servers` | ssh | Server identifiers to target (repeat or comma-separate) |
| `--http-method` | http | HTTP method (e.g. `GET`) |
| `--http-url` | http | URL to probe |
| `--http-expected-status` | http | Expected status code |
| `--http-body-match` | http | Substring expected in the response body |
| `--scanner` | vuln | `snyk`, `trivy`, or `custom` |
| `--scan-target-kind` | vuln | Target kind |
| `--scan-target` | vuln | Target path or identifier |
| `--severity-threshold` | vuln | Minimum severity that fails the check |
| `--fail-on-unfixed-only` | vuln | Only fail on findings with no available fix |
| `--sarif-output-path` | vuln | Where the scanner writes SARIF output |

SSH check:
```bash
dhq deployment-checks create -p my-app \
  --name "Run migrations" --stage post_deploy --check-type ssh \
  --command "bundle exec rails db:migrate" --servers srv_prod1,srv_prod2 --json
```

HTTP check:
```bash
dhq deployment-checks create -p my-app \
  --name "Health check" --stage post_deploy --check-type http \
  --http-method GET --http-url https://app.example.com/health --http-expected-status 200 --json
```

Vulnerability scan (pre_build only):
```bash
dhq deployment-checks create -p my-app \
  --name "Snyk scan" --stage pre_build --check-type vulnerability_scan \
  --scanner snyk --severity-threshold high --fail-on-unfixed-only --json
```

#### `dhq deployment-checks update <id>`

Partial update — only flags you pass are sent.

```bash
## Disable temporarily
dhq deployment-checks update chk_abc123 -p my-app --enabled=false --json

## Tighten the severity gate
dhq deployment-checks update chk_abc123 -p my-app --severity-threshold critical --json
```

#### `dhq deployment-checks delete <id>`
```bash
dhq deployment-checks delete chk_abc123 -p my-app
```

### Build Cache Files

Manage files/directories cached between builds to speed up deployments.

#### `dhq build-cache-files list`
```bash
dhq build-cache-files list -p my-app --json
```

#### `dhq build-cache-files create`

| Flag | Required | Description |
|------|----------|-------------|
| `--path` | yes | Path to cache |

```bash
dhq build-cache-files create -p my-app --path "node_modules" --json
dhq build-cache-files create -p my-app --path ".cache" --json
```

#### `dhq build-cache-files update <id>`
```bash
dhq build-cache-files update 12345 -p my-app --path "vendor" --json
```

#### `dhq build-cache-files delete <id>`
```bash
dhq build-cache-files delete 12345 -p my-app
```

### Build Languages

Set language runtime versions used by the build server.

#### `dhq build-languages set <language-id>`

| Flag | Required | Description |
|------|----------|-------------|
| `--version` | yes | Language version |
| `--build-config` | no | Build configuration override ID |

```bash
## Set Ruby version for project
dhq build-languages set ruby -p my-app --version "3.2" --json

## Set Node version for a specific build config override
dhq build-languages set node -p my-app --version "20" --build-config override-123 --json
```

**Tip:** Use `dhq language-versions list -p <project>` to see available versions.

### Build Known Hosts

Manage SSH known hosts for the build server (e.g. for private dependencies fetched during builds).

#### `dhq build-known-hosts list`
```bash
dhq build-known-hosts list -p my-app --json
```

#### `dhq build-known-hosts create`

| Flag | Required | Description |
|------|----------|-------------|
| `--hostname` | yes | SSH hostname |
| `--public-key` | yes | SSH public key |

```bash
dhq build-known-hosts create -p my-app --hostname "github.com" --public-key "ssh-rsa AAAA..." --json
```

#### `dhq build-known-hosts delete <id>`
```bash
dhq build-known-hosts delete 12345 -p my-app
```

<a id="ref-global-resources"></a>

### Global Resources

## Global Resources Reference

Account-level resources shared across projects.

### Global Servers

Server templates that can be copied to any project.

#### `dhq global-servers list`
```bash
dhq global-servers list --json
```

#### `dhq global-servers show <id>`
```bash
dhq global-servers show 12345 --json
```

#### `dhq global-servers create`

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | Server name |
| `--protocol` | yes | One of: ftp, sftp, ssh |
| `--path` | no | Deployment path |
| `--environment` | no | Environment label |

```bash
dhq global-servers create --name "Shared Staging" --protocol ssh --json
```

#### `dhq global-servers copy <id>`
Copy a global server into a project.

| Flag | Description |
|------|-------------|
| `-p` | Target project |
| `--name` | Override server name |

```bash
dhq global-servers copy 12345 -p my-app --json
dhq global-servers copy 12345 -p my-app --name "My Staging" --json
```

#### `dhq global-servers update <id>`
```bash
dhq global-servers update 12345 --name "Updated Name" --json
```

#### `dhq global-servers delete <id>`
```bash
dhq global-servers delete 12345
```

### Global Environment Variables

#### `dhq global-env-vars list`
```bash
## Accessed through env-vars with global scope
dhq global-env-vars list --json
```

#### `dhq global-env-vars create`
```bash
dhq global-env-vars create --name SHARED_SECRET --value "abc123" --json
```

#### `dhq global-env-vars update <id>`
```bash
dhq global-env-vars update 12345 --value "new-value" --json
```

### Global Config Files

Account-level config files shared across projects.

#### `dhq global-config-files list`
```bash
dhq global-config-files list --json
```

#### `dhq global-config-files show <id>`
```bash
dhq global-config-files show 12345 --json
```

#### `dhq global-config-files create`

| Flag | Required | Description |
|------|----------|-------------|
| `--name` | yes | File name |
| `--body` | yes | File content |

```bash
dhq global-config-files create --name ".env.shared" --body "RAILS_ENV=production" --json
```

#### `dhq global-config-files update <id>`
```bash
dhq global-config-files update 12345 --body "RAILS_ENV=staging" --json
```

#### `dhq global-config-files delete <id>`
```bash
dhq global-config-files delete 12345
```

### SSH Keys

#### `dhq ssh-keys list`
```bash
dhq ssh-keys list --json
```

#### `dhq ssh-keys create`
```bash
dhq ssh-keys create --name "Deploy Key" --public-key "ssh-rsa AAAA..." --json
```

### Templates

#### `dhq templates list`
List custom project templates.

```bash
dhq templates list --json
```

#### `dhq templates show <id>`
```bash
dhq templates show 12345 --json
```

#### `dhq templates create`
```bash
dhq templates create --name "Rails App" --config '{"..."}' --json
```

#### `dhq templates public`
List public (built-in) templates.

```bash
dhq templates public --json
```

#### `dhq templates public show <id>`
```bash
dhq templates public show 12345 --json
```

### Other Global Resources

#### Zones
```bash
dhq zones list --json
```

#### Language Versions
```bash
dhq language-versions list --json
```

#### Network Agents
```bash
dhq agents list --json
dhq agents create --name "Office Agent" --json
```

#### Integrations
```bash
dhq integrations list -p my-app --json
dhq integrations create -p my-app --type slack_oauth --json
dhq integrations create -p my-app --type google_chat --config '{"url":"https://chat.googleapis.com/v1/spaces/..."}' --json
dhq integrations create -p my-app --type telegram --config '{"bot_token":"...","chat_id":"..."}' --json
dhq integrations create -p my-app --type microsoft_teams --config '{"url":"...","team":"..."}' --json
dhq integrations create -p my-app --type discord --json
```

Available types: `slack_oauth`, `google_chat`, `telegram`, `microsoft_teams`, `discord`, `http_req`, `cloudflare`, `new_relic`, `rollbar`, `sentry`, `bugsnag`, `honeybadger`, `git_deployment_status`.

Deprecated (use alternatives): `slack` (use `slack_oauth`), `flowdock`, `campfire`, `http_post` (use `http_req`).

#### Auto-Deploys
```bash
dhq auto-deploys list -p my-app --json
dhq auto-deploys enable -p my-app --branch main --server Production --json
```

#### Scheduled Deploys
```bash
dhq scheduled-deploys list -p my-app --json
dhq scheduled-deploys create -p my-app --cron "0 2 * * *" --branch main --server Production --json
```

<a id="ref-operations"></a>

### Operations

## Operations Reference

Monitoring, diagnostics, and utility commands.

### Activity

#### `dhq activity list`
View recent deployment activity/events.

```bash
dhq activity list --json
dhq activity list -p my-app --json
```

#### `dhq activity stats`
Show deployment statistics.

```bash
dhq activity stats --json
dhq activity stats -p my-app --json
```

### Status

#### `dhq status`
Dashboard view of project health: recent deployments, server status, project summary.

```bash
dhq status -p my-app --json
```

### Test Access

#### `dhq test-access`
Test server connectivity.

```bash
## Test all servers in project
dhq test-access -p my-app --json

## Test specific server
dhq test-access -p my-app --server Production --json
```

#### `dhq test-access show <result-id>`
Show detailed test result.

```bash
dhq test-access show abc123 -p my-app --json
```

### Doctor

#### `dhq doctor`
Diagnose CLI configuration and environment. Shows:
- CLI version
- Config files loaded
- Credentials status
- Git status (if in repo)
- Network connectivity

```bash
dhq doctor
```

### Raw API Access

#### `dhq api <method> <path>`
Escape hatch for any API endpoint.

| Argument | Description |
|----------|-------------|
| `<method>` | HTTP method: GET, POST, PUT, PATCH, DELETE |
| `<path>` | API path |

| Flag | Description |
|------|-------------|
| `--body` | JSON request body |

```bash
dhq api GET /projects
dhq api GET /projects/my-app/deployments
dhq api POST /projects/my-app/deployments --body '{"deployment":{"branch":"main"}}'
dhq api DELETE /projects/my-app/servers/12345
```

### URL Utilities

#### `dhq url parse <url>`
Parse a DeployHQ URL into components.

```bash
dhq url parse "https://myaccount.deployhq.com/projects/my-app/deployments/abc123"
```

Returns: account, resource, project, sub_resource, id.

#### `dhq show <url>`
Fetch and display any DeployHQ resource by URL. Auto-detects resource type.

```bash
dhq show "https://myaccount.deployhq.com/projects/my-app" --json
```

### Utility

#### `dhq open [permalink]`
Open project in browser.

```bash
dhq open my-app
dhq open  # opens current project (from .deployhq.toml)
```

#### `dhq commands-catalog`
List all CLI commands and subcommands. Useful for agent introspection.

```bash
dhq commands-catalog --json
```

#### `dhq version`
```bash
dhq version
```

#### `dhq update`
Update CLI to latest version.

```bash
dhq update
```

<a id="ref-auth-setup"></a>

### Auth Setup

## Authentication & Setup Reference

### Authentication

#### `dhq auth login`
Login interactively or with flags.

| Flag | Description |
|------|-------------|
| `--account` | Account subdomain |
| `--email` | Login email |
| `--api-key` | API key |

```bash
## Interactive (prompts for missing fields)
dhq auth login

## Non-interactive (agent-friendly)
dhq auth login --account mycompany --email user@example.com --api-key abc123
```

#### `dhq auth logout`
Clear stored credentials.

```bash
dhq auth logout
```

#### `dhq auth status`
Show current authentication info.

```bash
dhq auth status
dhq auth status --json
```

#### `dhq auth token`
Display current API token (masked).

```bash
dhq auth token
```

#### Environment Variables (CI/Agent)
```bash
export DEPLOYHQ_ACCOUNT=mycompany
export DEPLOYHQ_EMAIL=user@example.com
export DEPLOYHQ_API_KEY=abc123
```

No login needed when these are set.

### Signup

#### `dhq signup`
Create new DeployHQ account.

| Flag | Required | Description |
|------|----------|-------------|
| `--email` | yes | Account email |
| `--password` | yes | Account password |
| `--account-name` | no | Custom subdomain (auto-generated if omitted) |

```bash
dhq signup --email user@example.com --password "..."
```

### CLI Configuration

#### `dhq configure init`
Initialize a config file in the current directory.

```bash
dhq configure init  # creates .deployhq.toml
```

#### `dhq configure show`
Display current config with sources.

```bash
dhq configure show
```

#### `dhq configure set <key> <value>`
Set a config value.

```bash
dhq configure set project my-app
dhq configure set account mycompany
```

#### `dhq configure unset <key>`
Remove a config value.

```bash
dhq configure unset project
```

#### Config File Format (`.deployhq.toml`)
```toml
project = "my-app"
account = "mycompany"
```

#### Config Precedence
1. CLI flags (`--project`, `--account`)
2. Environment variables (`DEPLOYHQ_PROJECT`, `DEPLOYHQ_ACCOUNT`)
3. `.deployhq.toml` (current directory, searched up to root)
4. `~/.deployhq/config.toml` (user home)

### Agent Setup

#### `dhq setup claude`
Install Claude Code integration files.

| Flag | Description |
|------|-------------|
| `--project` | Install to project directory (`.claude/`) instead of user (`~/.claude/`) |
| `--uninstall` | Remove integration files |

```bash
dhq setup claude
dhq setup claude --project
dhq setup claude --uninstall
```

#### `dhq setup codex`
Install OpenAI Codex integration.

```bash
dhq setup codex
```

#### `dhq setup cursor`
Install Cursor integration.

```bash
dhq setup cursor
```

#### `dhq setup windsurf`
Install Windsurf integration.

```bash
dhq setup windsurf
```

#### `dhq mcp`
Show MCP (Model Context Protocol) server configuration.

```bash
dhq mcp
```

### Telemetry

#### `dhq telemetry status`
```bash
dhq telemetry status
```

#### `dhq telemetry enable` / `dhq telemetry disable`
```bash
dhq telemetry enable
dhq telemetry disable
```

### Shell Completion

```bash
## Bash
eval "$(dhq completion bash)"

## Zsh
eval "$(dhq completion zsh)"

## Fish
dhq completion fish | source

## PowerShell
dhq completion powershell | Out-String | Invoke-Expression
```

### First-Time Setup

#### `dhq hello`
Interactive guided setup for new users:
1. Login or signup
2. Project selection
3. Quick orientation

#### `dhq init`
Interactive project setup wizard:
1. Project name + SCM + repo URL + branch
2. Deploy key setup
3. Server protocol + credentials
4. Optional first deployment