DeployHQ CLI: Deploy From Your Terminal (or Let Your AI Agent Do It)

If you have ever wished you could deploy without leaving your terminal — no browser tab, no dashboard click, no context switch — that is exactly what the new DeployHQ CLI is built for. It is a single Go binary, called dhq, that wraps the entire DeployHQ API. You install it once and you can trigger deployments, watch them in real time, tail logs, and roll back from the command line. And because the output is machine-readable by default, your AI coding assistant can do the same thing on your behalf.

This guide walks through installing the CLI, authenticating, running your first deployment, watching it live, tailing logs, and rolling back. Then we cover the part most teams care about in 2026: wiring dhq into Claude Code, Cursor, Codex, and Windsurf so an AI coding agent can drive your deployments end to end.

Why a Terminal-First Deployment Tool Matters

Deploy steps are the easiest place for an engineering workflow to break flow. You finish a fix, you push, the test suite passes — and then you alt-tab to a browser to click a button. With a CLI on your $PATH, that step collapses into a single command. With the same CLI exposed to your AI assistant, the deploy step disappears from your workflow entirely: the assistant proposes it, you approve, it ships.

That second use case — agent-driven deployment — is why DeployHQ rebuilt the CLI from scratch. The previous Ruby gem (gem install deployhq) is now deprecated. The new tool, dhq, follows a strict output contract designed for both humans and agents:

• stdout is always data — a clean table for humans, JSON when piped or when --json is set
• stderr is always human messages — progress, warnings, errors
• No interactive prompts when all required flags are provided

If you have read our take on why CLIs are the cleanest integration surface for AI coding agents, this is what that argument looks like in practice for deployments.

Installing the DeployHQ CLI

dhq ships as a single binary for macOS, Linux, and Windows (amd64 and arm64). Pick the install method that matches your environment:

# macOS (Homebrew)
brew install deployhq/tap/dhq

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

# Windows (Scoop)
scoop bucket add deployhq https://github.com/deployhq/scoop-bucket
scoop install dhq

# From source (Go)
go install github.com/deployhq/deployhq-cli/cmd/dhq@latest

After install, confirm the binary is on your $PATH:

dhq --version

Both dhq --version and dhq version work — use whichever fits your scripts.

Authenticating

dhq supports two authentication paths: an interactive login that stores credentials in your OS keyring (for everyday human use), and environment variables (for CI runners and AI agents).

For the interactive flow:

dhq auth login

You will be prompted for your account domain (e.g. my-account.deployhq.com), your email, and an API key from Settings → Security. You can create or revoke API keys from the DeployHQ API settings page.

For non-interactive environments — CI runners, Docker images, AI agent sandboxes — set three environment variables instead:

export DEPLOYHQ_ACCOUNT="my-account"
export DEPLOYHQ_EMAIL="you@example.com"
export DEPLOYHQ_API_KEY="..."

This is the same pattern we recommend when pointing AI agents at CI/CD pipelines: credentials live in the runner's secret store, never in prompts or repo files.

Your First Deployment

The five commands you will reach for most often:

A typical session looks like this. Discover what you have access to:

$ dhq projects list
NAME              PERMALINK         REPO
api-service       api-service       github.com/acme/api
marketing-site    marketing-site    github.com/acme/marketing

$ dhq servers list -p api-service
NAME         IDENTIFIER    TYPE   BRANCH    PATH
production   prod-srv-01   SSH    main      /var/www/api
staging      stage-srv-01  SSH    main      /var/www/api-staging

Then deploy. With --wait, you get a live TUI progress bar that updates as the deployment runs through its phases (fetch repo → build → upload → run SSH commands):

$ dhq deploy -p api-service -s staging --wait

When the deployment is done, the CLI exits with status 0 on success and non-zero on failure — exactly what your shell scripts and CI runners need.

Watching, Logs, and Rollback

Three operations turn the CLI from a fire and forget trigger into a control plane you can run from one terminal window.

Watch a deployment live. If a deploy is already in flight, attach to it from anywhere:

dhq deployments watch -p api-service

The watch view streams the same TUI you would see from --wait, but for a deployment that started elsewhere — useful when a teammate or a CI job kicked it off and you want to monitor without refreshing the dashboard.

Tail logs after the fact. When something fails, you want the full log without scrolling through the web UI:

dhq deployments logs DEP-12345 -p api-service

For agent-friendly output, add --json and pipe into jq:

dhq deployments logs DEP-12345 -p api-service --json | jq '.data.entries[] | select(.level=="error")'

Roll back a bad deploy. If a release goes sideways, revert to the previous successful deployment:

dhq rollback DEP-12345 -p api-service --wait

Rollback uses the same diff engine as a forward deploy, so the only files that move are the ones that changed. This is the same one-click rollback primitive exposed in the web UI, just from your terminal.

Output Contract: Why It Matters for AI Agents

Most CLIs were not designed to be called by AI coding agents. They mix progress messages with data on stdout, throw interactive prompts when you forget a flag, and return unstructured text that the agent has to guess how to parse.

dhq was built around three rules that fix that:

1. stdout is data, stderr is text — a piped command always returns parseable output; status messages never pollute it
2. JSON on demand, JSON when piped — dhq deploy ... --json returns machine-readable output, and the same auto-switches when stdout is a pipe
3. Breadcrumbs in every JSON response — the CLI tells the agent what to do next

A typical JSON response includes a breadcrumbs array that explicitly lists the next reasonable command:

{
  "ok": true,
  "data": { "deployment_id": "DEP-12345", "status": "completed" },
  "summary": "Deployment DEP-12345 to staging completed in 47s",
  "breadcrumbs": [
    {"action": "logs", "cmd": "dhq deployments logs DEP-12345 -p api-service"},
    {"action": "rollback", "cmd": "dhq rollback DEP-12345 -p api-service"}
  ]
}

The agent does not have to memorise the command surface. It runs one command, reads the breadcrumbs, and knows what to chain next. On failure the envelope flips — {ok: false, error, recovery} — so the agent gets the same structured handle on what went wrong and what to try next.

Wiring dhq Into Your AI Coding Assistant

This is where the real workflow change happens. With dhq on $PATH and the right rules file in your repo, your AI editor can deploy your code without you ever opening a browser. A full companion guide on driving DeployHQ from Cursor, Claude Code, and Windsurf is in the works (sister post coming Week 7) — what follows is the short version.

The pattern is the same across all four editors below: the capability lives in the editor's permissions config; the judgement lives in a behavioural rules file. Read-only commands (projects list, servers list, deployments logs, deployments watch) are safe by default. Destructive ones (deploy, rollback) should require an explicit human approval gate.

Claude Code

Claude Code governs shell access through .claude/settings.json. Allow the read-only dhq commands; require approval for the destructive ones:

{
  "permissions": {
    "allow": [
      "Bash(dhq projects:*)",
      "Bash(dhq servers list:*)",
      "Bash(dhq deployments logs:*)",
      "Bash(dhq deployments watch:*)"
    ],
    "ask": [
      "Bash(dhq deploy:*)",
      "Bash(dhq rollback:*)"
    ]
  }
}

Then drop a CLAUDE.md block at the project root telling Claude when to reach for the CLI. Behavioural rules belong in CLAUDE.md; we cover the full pattern in our guide to CLAUDE.md, AGENTS.md and Copilot Instructions:

## Deployment

This project uses DeployHQ. Use the `dhq` CLI for all deploys.

- After the test suite passes on a branch, propose `dhq deploy -p <project> -s staging --wait` and wait for my approval.
- Never run `dhq deploy ... -s production` without an explicit instruction containing the word "production".
- For a failing deploy, fetch logs with `dhq deployments logs <id>` before suggesting a fix.
- For a regression in production, propose `dhq rollback <id>` first, then debug.

Cursor

Cursor's Composer agent shells out the same way. Drop the rules in .cursor/rules/deployhq.mdc — that is the path current Cursor versions auto-load, with .mdc frontmatter:

We deploy with DeployHQ via the `dhq` CLI.

When asked to deploy:
1. Confirm the target environment in your message before running the command.
2. Use `dhq deploy -p <project> -s staging --wait` for staging.
3. For production, ask me to confirm in the chat before issuing the command.
4. After triggering, check `dhq deployments watch` until completion or failure.
5. On failure, run `dhq deployments logs <id>` and summarise the error before suggesting a fix.

Codex CLI / Windsurf

OpenAI's Codex CLI and Windsurf's Cascade agent both run shell commands natively. Once dhq is on $PATH they can call it without extra config — the work is in giving them the right behavioural rules so they do not deploy the moment they feel confident. We compared the three terminal agents in detail in Claude Code vs Codex CLI vs Gemini CLI, and the deployment pattern that emerged is the same: read commands open, write commands gated by an explicit instruction.

For an even shorter setup, dhq setup writes the right files for each editor in the right place — no manual config copying:

dhq setup claude     # writes ~/.claude/skills/deployhq/SKILL.md
dhq setup cursor     # writes .cursor/rules/deployhq.mdc in the current repo
dhq setup codex      # writes AGENTS.md in the current repo
dhq setup windsurf   # writes global_rules.md

Each variant installs a behavioural rules file the editor actually auto-loads, plus a SKILL.md decision tree and reference docs that teach the agent when each dhq command is appropriate. More on the design choices behind that in our piece on the developer CLIs that AI coding agents actually use well.

Using dhq in CI/CD

The same output contract that makes the CLI work for AI agents makes it trivial to drop into CI. A minimal GitHub Actions step:

env:
  DEPLOYHQ_ACCOUNT: ${{ secrets.DEPLOYHQ_ACCOUNT }}
  DEPLOYHQ_EMAIL:   ${{ secrets.DEPLOYHQ_EMAIL }}
  DEPLOYHQ_API_KEY: ${{ secrets.DEPLOYHQ_API_KEY }}

steps:
  - name: Install dhq
    run: curl -fsSL https://deployhq.com/install/cli | sh

  - name: Deploy to staging
    run: dhq deploy -p api-service -s staging --wait --json

Auth via env vars, JSON output for machine parsing, exit code drives the build status. If the deploy fails, the CI job fails — no extra plumbing required. For more on running AI agents inside the same kind of pipeline, see our piece on agentic workflows in CI/CD.

Migrating From the Old Ruby Gem

If you have the old gem install deployhq tool installed, the migration is straightforward:

1. Install dhq using one of the methods above.
2. Run dhq auth login (or set the DEPLOYHQ_* environment variables) — your existing API keys still work.
3. Update any scripts that called deployhq deploy to dhq deploy -p <project> -s <server>.
4. Once everything is working, gem uninstall deployhq to remove the old tool.

The old Deployfile JSON format is no longer required — dhq reads project context from flags, environment variables, or your interactive auth state. This is a breaking change, but a small one: most users had a single Deployfile per repo, and the new flags are easier to drop into Makefiles, scripts, and CI configs.

Where to Go Next

The CLI is one piece of a larger story. DeployHQ is increasingly designed for both humans and agents — the DeployHQ agents page walks through how the platform thinks about tool design for AI editors, and where we are heading next.

If you do not have a DeployHQ account yet, start a free trial — install dhq, point it at your first project, and you can run an automated deployment from your terminal inside ten minutes.

Questions, edge cases, or feedback on the CLI? We would love to hear from you — drop us a line at support@deployhq.com or find us on @deployhq.