The DeployHQ CLI is designed for scripting and automation. Every command supports JSON output, and the `dhq api` escape hatch provides access to all 144+ API endpoints.

## The Output Contract

The CLI separates data from messages:

- **stdout** is always data (table format for humans, JSON for machines)
- **stderr** is always human-readable messages (progress, errors, hints)

This means you can safely pipe stdout to `jq` or other tools without worrying about progress messages contaminating the output.

## JSON Output

### Basic JSON

Add `--json` to any command:

```bash
dhq projects list --json
dhq servers list -p my-app --json
dhq deployments show abc123 -p my-app --json
```

### Field Selection

Select specific fields to reduce output size:

```bash
dhq projects list --json name,permalink,zone
dhq deployments list -p my-app --json identifier,status,branch
```

### Automatic JSON in Pipes

When stdout is piped (not a terminal), the CLI automatically switches to JSON output:

```bash
# These produce the same result
dhq projects list --json | jq '.data'
dhq projects list | jq '.data'   # auto-detects pipe, outputs JSON
```

## Working with jq

Common patterns for extracting data:

```bash
# Get a project's permalink
dhq projects list --json | jq -r '.data.records[0].permalink'

# Get the status of the latest deployment
dhq deployments list -p my-app --json | jq -r '.data.records[0].status'

# Get the latest deployment ID
dhq deployments list -p my-app --json | jq -r '.data.records[0].identifier'

# List all server names
dhq servers list -p my-app --json | jq -r '.data.records[].name'

# Filter failed deployments
dhq deployments list -p my-app --json | jq '.data.records[] | select(.status == "failed")'
```

## Breadcrumbs

JSON responses include a `breadcrumbs` array with suggested next commands:

```json
{
  "ok": true,
  "data": { "identifier": "abc123", "status": "completed" },
  "summary": "Deployment abc123 completed",
  "breadcrumbs": [
    {"action": "logs", "cmd": "dhq deployments logs abc123 -p my-app"},
    {"action": "rollback", "cmd": "dhq rollback abc123 -p my-app"}
  ]
}
```

This is particularly useful for AI agents that can follow breadcrumbs to perform multi-step workflows.

## JSONL Operation Log

Set the `DEPLOYHQ_OUTPUT_FILE` environment variable to capture all CLI operations as JSONL (one JSON object per line):

```bash
export DEPLOYHQ_OUTPUT_FILE=/tmp/deployhq.jsonl
dhq deploy -p my-app --server production --wait
dhq servers list -p my-app
cat /tmp/deployhq.jsonl
```

Each line in the file is a complete JSON record of one operation, useful for auditing and debugging automation scripts.

## The API Escape Hatch

`dhq api` lets you make raw HTTP requests to any DeployHQ API endpoint. This covers all 144+ endpoints, including those not yet available as dedicated CLI commands.

### Syntax

```bash
dhq api <METHOD> <PATH> [--body '<JSON>']
```

### Examples

```bash
# GET requests
dhq api GET /projects
dhq api GET /projects/my-app
dhq api GET /projects/my-app/environment_variables

# POST requests
dhq api POST /projects/my-app/config_files \
  --body '{"config_file":{"path":".env","body":"KEY=val"}}'

# PUT requests
dhq api PUT /projects/my-app/servers/srv-123 \
  --body '{"server":{"name":"New Name"}}'

# DELETE requests
dhq api DELETE /projects/my-app/excluded_files/abc123
```

### When to Use dhq api

Use `dhq api` when:

- You need an endpoint not available as a dedicated command
- You want to test API calls before writing automation
- You need exact control over the request body
- You are following the [API documentation](https://www.deployhq.com/support/api) and want to replicate examples from the CLI

## Scripting Examples

### Deploy and Report Status

```bash
#!/bin/bash
set -e

RESULT=$(dhq deploy -p my-app -s production --revision "$1" --wait --json)
STATUS=$(echo "$RESULT" | jq -r '.data.status')
DEP_ID=$(echo "$RESULT" | jq -r '.data.identifier')

if [ "$STATUS" = "completed" ]; then
  echo "Deployment $DEP_ID succeeded"
else
  echo "Deployment $DEP_ID failed with status: $STATUS"
  dhq deployments logs "$DEP_ID" -p my-app
  exit 1
fi
```

### List All Projects and Their Servers

```bash
for permalink in $(dhq projects list --json | jq -r '.data.records[].permalink'); do
  echo "=== $permalink ==="
  dhq servers list -p "$permalink" --json | jq -r '.data.records[].name'
  echo
done
```

### Export Environment Variables to a File

```bash
dhq env-vars list -p my-app --json | jq -r '.data.records[] | "\(.name)=\(.value)"' > .env.backup
```