Last updated on 18th November 2026

Deploying with the CLI

The DeployHQ CLI provides several ways to create and manage deployments, from a quick one-liner to detailed deployment management commands.

One-Command Deploy (dhq launch)

dhq launch takes a project folder to a live URL on DeployHQ's managed infrastructure in a single step. It detects your framework, provisions the right target -- Static Hosting or a Managed VPS -- connects your repository, deploys, and prints the URL when it finishes.

# Interactive: detect the framework and prompt for anything missing
dhq launch

# Force Static Hosting with a chosen subdomain
dhq launch --static --subdomain my-app

# Provision a Managed VPS in a specific region and size
dhq launch --vps --accept-cost --region lon1 --size s-1vcpu-1gb

A Managed VPS is a managed resource -- free for early customers during the beta, and billed monthly afterwards. Because it has a cost, provisioning one non-interactively requires --accept-cost; --yes on its own never provisions a VPS. A Managed VPS also needs a payment method on the account; Static Hosting does not (an account that is not paying yet can have one site, and paying accounts can have more).

For CI or AI agents, dhq launch is fully non-interactive with structured output:

# Structured JSON, never prompts
dhq launch --static --json

# Preview the intended actions and cost without making any changes
dhq launch --vps --dry-run --json

Run this way with no project configured, dhq launch reuses the project already connected to this repository, or creates one named after the repository, so it also works in an account with no projects yet. If the account has exactly one project, that project is used. If more than one project could be the right one, dhq launch stops without creating anything and lists them; pass --project to choose. --dry-run reports the project it would use or create.

Useful flags:

Flag Description
--static / --vps Force the deployment target
--subdomain Static Hosting subdomain
--custom-domain Your own domain for the Static Hosting site (paid plans, including trials)
--no-pair With --custom-domain, add only that domain, not its www or apex version
--region / --size Managed VPS region and size slugs
--branch Branch to deploy (defaults to the repository default)
--project Reuse an existing project instead of creating one
--accept-cost Acknowledge Managed VPS cost (required for non-interactive VPS provisioning)
--cleanup-on-failure Remove the provisioned server if the deploy fails
--dry-run Print intended actions and cost without executing
--non-interactive / --yes Never prompt; fail fast on ambiguity (for CI and agents)

dhq launch deploys straight away, and every file in the repository is uploaded unless it is excluded. If some files must not be published, such as a deploy script or local configuration, create the project first, exclude them, then launch it:

dhq projects create --name my-app
dhq excluded-files create -p my-app --path deploy.sh
dhq launch --static --project my-app

Launching on Your Own Domain

Add --custom-domain to put a Static Hosting site on a domain you own. The www or apex version is added too, unless you pass --no-pair. Custom domains are available on paid plans, including trials, and only on Static Hosting, so --custom-domain is refused with --vps.

dhq launch --static --subdomain my-app --custom-domain example.com

The site goes live on its deployhq-sites.com address straight away, and that remains the address dhq launch reports. When the deployment finishes, dhq launch waits up to a minute for the domain to be set up, then prints the CNAME and TXT records to publish at your DNS provider. For an apex domain such as example.com, use an ALIAS or ANAME record, or CNAME flattening, in place of the CNAME. The domain goes live automatically once both records are detected. If the wait runs out, get the records later with dhq domains show.

If DeployHQ refuses the hostname, for example because it is not a valid domain or is already in use, nothing is provisioned and the command fails with the reason custom_domain_invalid. Any other problem with the domain, such as a plan without custom domains or too many requests, does not stop the launch: the site still goes live, the command exits successfully, and it tells you what happened and what to do next.

With --json, the result has a custom_domain object:

Field Description
status dns_records_required, registering, active, failed or not_added
domains The domains added, each with its dns_records
errors Why something could not be done
retryable true when trying again later may work
next_step What to do next

Running dhq launch --custom-domain again in a folder that has already launched adds the domain to the existing site, or reports it if it is already there. --dry-run shows the domain it would add without changing anything. In a terminal, dhq launch offers to add a custom domain if you did not pass one; it never asks when running non-interactively.

To manage the domain afterwards, see Managing Servers with the CLI.

After the first run, dhq launch saves the new project to a .deployhq.toml file in the current folder (together with its account), so subsequent deployments are just dhq deploy. The file is only written inside a git repository, and a re-run after a failure reuses the saved project instead of creating another. An existing .deployhq.toml is overwritten with the project, server and target dhq launch used. If a project with the same name already exists, dhq launch asks before creating a new one in a terminal, and fails without one.

Quick Deploy

The dhq deploy shortcut is the fastest way to deploy:

# Deploy the default project to the default server
dhq deploy --wait

# Deploy a specific project to a specific server
dhq deploy -p my-app -s production --wait

# Deploy a specific branch
dhq deploy -p my-app -s staging --branch develop --wait

# Deploy a specific commit
dhq deploy -p my-app -s production --revision abc123 --wait

dhq deploy starts a deployment on your servers, so AI agents and automation tools that read dhq commands --json will see it flagged as requiring confirmation. Run it only when you intend to change what is live.

Incremental and Full Deployments

Deployments are incremental by default: the start revision is the commit last successfully deployed to the server, so only the changes since then are transferred. Use these flags to change that:

# Deploy the entire branch from the first commit
dhq deploy -p my-app -s production --full --wait

# Deploy a specific range of commits (useful for hotfixes)
dhq deploy -p my-app -s production --start-revision a1b2c3d --revision e4f5g6h --wait

# Preview what would be deployed without executing
dhq deploy -p my-app -s production --dry-run

--dry-run cannot be combined with --wait.

The --wait Flag

By default, dhq deploy queues the deployment and returns immediately. Add --wait (or -w) to watch the deployment until it completes or fails. To stop waiting after a set time, add --timeout <seconds>; the default of 0 means no timeout.

dhq deploy -p my-app -s production -w --timeout 600

Live TUI Progress

When running in an interactive terminal with --wait, the CLI displays a real-time TUI (text user interface) showing deployment steps as they happen:

Deploying my-app to Production Web...

  Checking access to repository              [done]
  Updating repository                        [done]
  Running build commands                     [in progress]
    npm install                              [done]
    npm run build                            [running]
  Transferring files to server               [pending]

Elapsed: 1m 23s

Fuzzy Server Matching

Server names are fuzzy-matched, so you do not need to type the exact name:

# "prod" matches "Production Web"
dhq deploy -p my-app -s prod --wait

# "fedora" matches "DO - FEDORA"
dhq deploy -p my-app -s fedora --wait

If multiple servers match, the CLI presents a picker in interactive mode, or returns an error in non-interactive mode.

Auto-Server Selection

If your project has only one server, the CLI selects it automatically -- no -s flag needed.

Deployment Management

For more control, use the dhq deployments subcommands.

Listing Deployments

# List recent deployments
dhq deployments list -p my-app

# Page through results
dhq deployments list -p my-app --page 2 --per-page 50

# JSON output with specific fields
dhq deployments list -p my-app --json identifier,status,branch

Viewing Deployment Details

dhq deployments show <deployment-id> -p my-app

Creating a Deployment (Full Control)

dhq deployments create -p my-app \
  --server production \
  --branch main \
  --revision abc123

dhq deployments create also accepts these options:

Flag Description
--parent Identifier of the server or server group to deploy to
--copy-config Copy config files
--run-build Run build commands (on by default)
--use-cache Use the build cache (on by default)

For example, to skip the build cache for a single deployment:

dhq deployments create -p my-app --server production --use-cache=false

Watching a Deployment

Monitor an in-progress deployment:

dhq deployments watch <deployment-id> -p my-app

Viewing Deployment Logs

dhq deployments logs <deployment-id> -p my-app

# Show the log for a single step only
dhq deployments logs <deployment-id> -p my-app --step <step-id>

Each entry shows its message and, under it, its detail (such as a command's output or the list of excluded files), as the deployment page in DeployHQ does. Add --json for the logs of every step as JSON.

On failure, the CLI automatically shows logs and suggests recovery commands.

Aborting a Deployment

Stop a running deployment:

dhq deployments abort <deployment-id> -p my-app

Rolling Back

Rollback to the previous deployment:

# Shortcut
dhq rollback <deployment-id> -p my-app

# Or via subcommand
dhq deployments rollback <deployment-id> -p my-app

Retrying a Failed Deployment

Retry the last failed deployment:

# Shortcut
dhq retry <deployment-id> -p my-app

# Or via subcommand
dhq deployments retry <deployment-id> -p my-app

Deploying to Server Groups

If your project has server groups configured, you can deploy to all servers in a group simultaneously by specifying the group name with the -s flag:

dhq deploy -p my-app -s "Production Group" --wait

Deploying Only What Changed

You do not need a special flag to deploy from the last deployed commit to the latest one -- that is the default. dhq deploy uses the commit last successfully deployed to the server as the start revision, so only new changes are sent:

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

To override this, use --full to deploy the entire branch from the first commit, or --start-revision and --revision to choose an exact range. See Incremental and Full Deployments above.

Failure Handling

When a deployment fails with --wait, the CLI automatically:

  1. Shows the deployment logs
  2. Displays suggested next commands (retry, rollback)
  3. Returns a non-zero exit code for CI/CD integration

Example failure output:

Deployment failed.

Suggested actions:
  dhq retry abc123 -p my-app        # Retry this deployment
  dhq rollback abc123 -p my-app     # Rollback to previous version
  dhq deployments logs abc123 -p my-app  # View full logs

Testing Connectivity

Before deploying, you can verify that DeployHQ can reach your repository and servers:

# Test all servers in a project
dhq test-access -p my-app

# Test a specific server
dhq test-access -p my-app -s production

# Wait for the test to complete
dhq test-access -p my-app --wait

This runs the same connectivity checks that DeployHQ performs before a deployment, helping you catch configuration issues (wrong credentials, firewall rules, SSH key problems) before they cause a deployment failure.

Common Workflows

Deploy After a Git Push

git push origin main
dhq deploy -p my-app -s production --wait

Check Status Before Deploying

# View current server revisions
dhq servers list -p my-app

# View recent deployment history
dhq deployments list -p my-app

# Then deploy
dhq deploy -p my-app -s production --wait

Deploy and Open in Browser

dhq deploy -p my-app --wait && dhq open my-app