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
--atomicturns atomic deployments on. Use--atomic=falseto turn it off.--atomic-strategyiscopy_release(the default) orcopy_cache.--atomic-retentionis 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.