Last updated on 18th November 2026

Managing Servers with the CLI

The DeployHQ CLI lets you manage all server configurations, including project servers, server groups, and account-wide global servers.

Project Servers

Listing Servers

dhq servers list -p my-app

This shows all servers configured for the project, grouped by server group where applicable. Use --page and --per-page to page through long lists.

Viewing Server Details

dhq servers show <server-identifier> -p my-app

Creating a Server

dhq servers create -p my-app \
  --name "Production Web" \
  --protocol-type ssh \
  --path /var/www/html

# Specify an environment
dhq servers create -p my-app \
  --name "Staging" \
  --protocol-type sftp \
  --path /home/deploy/staging \
  --environment staging

Supported protocol types include: ssh, ftp, sftp, s3, rackspace, heroku, elastic_beanstalk, and others depending on your account plan.

Protocol-Specific Flags

Each protocol type accepts additional flags specific to its connection requirements:

SSH / SFTP:

dhq servers create -p my-app \
  --name "Production Web" \
  --protocol-type ssh \
  --hostname example.com \
  --port 22 \
  --username deploy \
  --path /var/www/html

FTP:

dhq servers create -p my-app \
  --name "FTP Server" \
  --protocol-type ftp \
  --hostname ftp.example.com \
  --port 21 \
  --username deploy \
  --path /public_html

S3:

dhq servers create -p my-app \
  --name "S3 Bucket" \
  --protocol-type s3 \
  --bucket-name my-bucket \
  --region us-east-1 \
  --access-key-id AKIA... \
  --secret-access-key '<key>'

Run dhq servers create --help for the full list of flags for each protocol type.

SSH Key Authentication

When creating SSH or SFTP servers, you can automatically install your project's deploy key on the server:

dhq servers create -p my-app \
  --name "Production Web" \
  --protocol-type ssh \
  --hostname example.com \
  --username deploy \
  --path /var/www/html \
  --install-key

The --install-key flag copies the project SSH public key to the server's authorized_keys file, saving you from doing it manually.

To use an account-wide SSH key instead of the project's key, pass --use-ssh-keys together with --global-key-pair-id:

dhq servers create -p my-app \
  --name "Production Web" \
  --protocol-type ssh \
  --hostname example.com \
  --username deploy \
  --use-ssh-keys \
  --global-key-pair-id <key-identifier> \
  --path /var/www/html

--use-ssh-keys applies to ssh and rsync servers. --install-key also installs the global key when --global-key-pair-id is given.

Password-Only Servers

For FTP, FTPS, or SSH servers that use a password, use --password-stdin so the password is never written into your shell history. In a terminal it asks for the password with hidden input; you can also pipe the value in:

dhq servers create -p my-app \
  --name "FTP Server" \
  --protocol-type ftp \
  --hostname ftp.example.com \
  --username deploy \
  --password-stdin \
  --path /public_html

Avoid the --password <value> flag. A password typed into a command ends up in shell history, and in the history of any tool or AI agent that runs the command.

Atomic (Zero-Downtime) Deployments

Atomic deployments publish each release to its own directory and switch over in one step, so visitors never see a half-deployed site. They are supported on ssh, rsync, digitalocean, hetzner_cloud, and managed_vps servers, and require an account with atomic deployments enabled.

dhq servers create -p my-app \
  --name "Production Web" \
  --protocol-type ssh \
  --hostname example.com \
  --username deploy \
  --use-ssh-keys \
  --path /var/www/app \
  --atomic \
  --atomic-strategy copy_release \
  --atomic-retention 5
  • --atomic turns atomic deployments on. Use --atomic=false to turn it off.
  • --atomic-strategy is copy_release (the default) or copy_cache.
  • --atomic-retention is the number of past releases to keep. It must be 1 or greater and defaults to 3.

Atomic deployments must be set before the server's first deployment. Changes are rejected afterwards.

Automatic Deployments and Branches

dhq servers create -p my-app \
  --name "Staging" \
  --protocol-type ssh \
  --hostname staging.example.com \
  --username deploy \
  --use-ssh-keys \
  --path /var/www/staging \
  --branch staging \
  --auto-deploy

--branch sets the branch the server deploys from (pass --branch "" to fall back to the repository default). --auto-deploy deploys automatically when new commits reach that branch; use --auto-deploy=false to turn it off. While a server belongs to a server group, the group's branch is used and automatic deployments are suppressed for the server.

Provider-Specific Flags

These flags apply only to the protocol shown in brackets:

Flag Protocol Purpose
--access-key-id, --secret-access-key, --bucket-name s3, s3_compatible S3 credentials and bucket
--custom-endpoint s3_compatible Endpoint URL of the S3-compatible service
--app-name, --api-key heroku Heroku app name and API key
--personal-access-token, --droplet-name digitalocean DigitalOcean token and droplet
--api-token, --hetzner-server-name hetzner_cloud Hetzner Cloud token and server
--access-token, --site-id netlify Netlify access token and site ID
--access-token, --store-url, --theme-name shopify Shopify access token, store, and theme
--subdomain, --subdirectory, --spa-mode static_hosting Site subdomain, output folder, and SPA routing (all paths rewrite to index.html)
--region, --size, --os-image, --key-pair-identifier, --accept-cost managed_vps Droplet region, size, image, SSH key, and cost acknowledgement

Static Hosting and Managed VPS are beta offerings and require the managed-resources beta to be enabled on your account. If it is not, dhq servers create fails and tells you to enroll first with dhq beta enroll --protocol static_hosting or dhq beta enroll --protocol managed_vps (this needs an account admin). 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 managed_vps, --os-image defaults to ubuntu-24-04-x64, and --key-pair-identifier takes an identifier from dhq ssh-keys list (omit it to let DeployHQ create and reuse its shared managed key). --accept-cost is required when creating a Managed VPS server non-interactively.

# Static Hosting site
dhq servers create -p my-app \
  --name "Site" \
  --protocol-type static_hosting \
  --subdomain my-app \
  --subdirectory dist

# Heroku app
dhq servers create -p my-app \
  --name "Heroku Staging" \
  --protocol-type heroku \
  --app-name my-app-staging \
  --api-key '<key>'

Creating a Server from a Global Template

If you maintain account-wide global servers (covered below), you can create a project server from one instead of re-entering its configuration:

dhq servers from-global <global-server-id> -p my-app

This is useful when many projects share the same server configuration.

Viewing Server Metrics (Beta)

Show a point-in-time snapshot of a server's metrics. This is a beta feature and works for SSH servers only:

dhq servers metrics <server-identifier> -p my-app

Updating a Server

dhq servers update <server-identifier> -p my-app --name "New Name"

servers update also accepts --path, --environment, --branch, --auto-deploy, and the atomic deployment flags described above:

# Turn on atomic deployments before the server's first deployment
dhq servers update <server-identifier> -p my-app \
  --atomic --atomic-strategy copy_cache --atomic-retention 5

# Turn automatic deployments off without changing anything else
dhq servers update <server-identifier> -p my-app --auto-deploy=false

Deleting a Server

dhq servers delete <server-identifier> -p my-app

Resetting a Host Key

If a server's SSH host key has changed (e.g., after server rebuild):

dhq servers reset-host-key <server-identifier> -p my-app

Server Groups

Server groups let you treat several servers as one deployment target. When you deploy to a group, the group's transfer order controls how the servers are processed.

Listing Server Groups

dhq server-groups list -p my-app

Use --page and --per-page to page through long lists.

Viewing a Server Group

dhq server-groups show <group-identifier> -p my-app

Creating a Server Group

dhq server-groups create -p my-app --name "Production Cluster"

# Choose how servers in the group are processed
dhq server-groups create -p my-app --name "Production Cluster" --transfer-order parallel

--transfer-order accepts one of two values. If you omit it, DeployHQ uses sequential.

  • sequential: each server's whole deployment runs as one unit, one server after another.
  • parallel: each step finishes on every server before any server starts the next step.

Updating a Server Group

dhq server-groups update <group-identifier> -p my-app --name "New Group Name"

# Change the transfer order
dhq server-groups update <group-identifier> -p my-app --transfer-order sequential

Deleting a Server Group

dhq server-groups delete <group-identifier> -p my-app

Global Servers

Global servers are account-wide server templates that can be copied to any project. This is useful when you have standard server configurations shared across projects.

Listing Global Servers

dhq global-servers list

Viewing a Global Server

dhq global-servers show <server-id>

Creating a Global Server

dhq global-servers create \
  --name "Standard Production" \
  --protocol ssh \
  --path /var/www/html

Updating a Global Server

dhq global-servers update <server-id> --name "Updated Name"

Copying a Global Server to a Project

dhq global-servers copy-to-project <server-id> --to-project my-app

Deleting a Global Server

dhq global-servers delete <server-id>

Custom Domains

Use dhq domains to serve a Static Hosting site on your own domain. Custom domains are available on paid plans, including trials, and only on Static Hosting servers. For how custom domains work, see Custom domains for Static Hosting. To launch a new site on your own domain in one step, see --custom-domain in Deploying with the CLI.

Each command takes the project (-p) and the Static Hosting server (-s, by name or identifier). In a folder set up by dhq launch you can leave out -s: the server saved in .deployhq.toml is used. The same commands also work for a global Static Hosting server; pass --global instead of -p, for example dhq domains list -s "Shared Site" --global. A global server always needs -s.

Adding a Domain

dhq domains add www.example.com -p my-site -s "My Site"

# Adds example.com and www.example.com
dhq domains add example.com -p my-site -s "My Site"

# Add only the hostname you typed
dhq domains add example.com -p my-site -s "My Site" --no-pair

# Return straight away, without waiting for the DNS records
dhq domains add www.example.com -p my-site -s "My Site" --no-wait

By default, add also adds the other half of the pair: a bare domain such as example.com gets www.example.com too, and the other way round. Use --no-pair to add only the hostname you typed.

add waits briefly while the domain is set up, then prints the DNS records to publish at your DNS provider: a CNAME record and a TXT record that proves you own the domain. For an apex domain such as example.com, use an ALIAS or ANAME record, or CNAME flattening, in place of the CNAME.

With --no-wait, the TXT record is not available yet. Run dhq domains show a moment later to see it.

The domain goes live automatically once both records are detected. A domain that is not verified within 7 days expires; remove it and add it again to start over.

Listing and Viewing Domains

dhq domains list -p my-site -s "My Site"

# Show one domain, with its status and DNS records
dhq domains show www.example.com -p my-site -s "My Site"

show accepts the hostname or the identifier of the domain.

Checking a Domain Now

DeployHQ checks pending domains automatically every few minutes. To check one straight away after publishing its records:

dhq domains check www.example.com -p my-site -s "My Site"

A domain can be checked once every 60 seconds.

Removing a Domain

dhq domains remove www.example.com -p my-site -s "My Site"

# Skip the confirmation prompt (required in non-interactive mode)
dhq domains remove www.example.com -p my-site -s "My Site" --yes

Removal happens in the background. The site keeps serving on its deployhq-sites.com address. Delete the domain's DNS records at your DNS provider once it is gone.