Last updated on 4th April 2026

JSON Output and Scripting

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:

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:

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:

# 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:

# 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")'

JSON responses include a breadcrumbs array with suggested next commands:

{
  "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):

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

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

Examples

# 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 and want to replicate examples from the CLI

Scripting Examples

Deploy and Report Status

#!/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

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

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