Dhq Deploy

DeployHQ CLI Deployment

Prerequisites

• dhq CLI installed and authenticated (dhq auth / dhq doctor)
• Know the project permalink — the short slug visible in the DeployHQ URL, e.g. my-project. This is NOT the UUID.

Critical: permalink vs UUID

dhq deploy and most commands require the project permalink (a short slug), not the UUID. Using a UUID returns a 404 from the DeployHQ API. Always confirm with dhq projects list if unsure.

Find project and server identifiers

# List all projects — shows permalink in the first column
dhq projects list

# List servers for a project
dhq servers list -p <permalink>

Deploy

Simplest case (single project, single server, latest commit)

dhq deploy --wait

--wait streams the deployment log in real time and exits non-zero on failure.

Explicit: specific project, server, and revision

dhq deploy -p <permalink> -s <server-identifier> -r <git-sha> --wait

Preview without deploying

dhq deploy -p <permalink> --dry-run

Watch an existing deployment

If a deployment was triggered without --wait:

dhq deployments watch <deployment-id> -p <permalink>

Common flags

Check result and duration

--wait exits non-zero on failure and prints final status inline. To inspect duration or retrieve the deployment ID for further commands:

# Most recent deployments with status and duration
dhq deployments list -p <permalink>

# Full details for a specific deployment
dhq deployments show <deployment-id> -p <permalink>

# Machine-readable (status, duration_seconds, etc.)
dhq deployments show <deployment-id> -p <permalink> --json

Auto Deploy on push

DeployHQ's own Auto Deploy is a per-server toggle, independent of the CLI's manual dhq deploy — it does not require dhq to be running anywhere. Verify or enable it directly:

# Show each server's auto-deploy status + preferred branch, and the account's deploy webhook URL
dhq auto-deploys list -p <permalink>

# Enable (or --disable) auto-deploy for a specific server
dhq auto-deploys enable -p <permalink> --server <server-identifier>

dhq auto-deploys list returns each deployable with auto_deploy: true|false and its preferred_branch — auto-deploy only fires for a push to that server's configured branch, not any push to the repo. The same response also includes the account's webhook_url (https://<account>.deployhq.com/deploy/<permalink>/<token>) — this is the actual trigger: DeployHQ deploys when that webhook receives a push notification, not by polling the repo itself. If the project's repository was added to DeployHQ via its native GitHub/GitLab/Bitbucket integration, the webhook is normally auto-registered; if the repo uses a different connection method (e.g. manual git URL, SSH-only), confirm the webhook is actually configured on the git host's side (repo Settings → Webhooks) and points at that same URL.

If push-triggered deploys aren't achievable this way for a given host/CI setup, trigger dhq deploy explicitly from a CI step instead, e.g. a GitHub Actions step on push to master:

- name: Deploy via DeployHQ
  run: dhq deploy -p <permalink> -s <server-identifier> --wait
  env:
    DEPLOYHQ_ACCOUNT: <subdomain>
    DEPLOYHQ_EMAIL: ${{ secrets.DEPLOYHQ_EMAIL }}
    DEPLOYHQ_API_KEY: ${{ secrets.DEPLOYHQ_API_KEY }}

Post-deploy

DeployHQ runs any SSH commands configured on the server (e.g. composer install, sake dev/build, OPcache flush) automatically after the file transfer. No manual post-deploy steps are needed unless something is not in the server's SSH command list.

Troubleshooting