The DeployHQ CLI

Last updated on 11th November 2025

As well as the web interface, DeployHQ also has a Ruby API library and command line tool for interacting with your projects.

You can find more information about the CLI client on GitHub, and installation and example usage instructions below.

Note: The CLI is currently experimental and under active development. Contributions are welcome via GitHub pull requests.

Installation

You'll need Ruby 2.7.8 or later installed on your system to be able to use the DeployHQ CLI. To get started, enter the following command in your terminal, in any directory, which will install the library globally.

gem install deployhq

Configuration (deployhq configure)

To configure the DeployHQ CLI in a project, navigate to your project in your terminal, then run deployhq configure to set up the connection to your project in DeployHQ, and follow the steps provided:

$ cd /path/to/project
$ deployhq configure
Account Domain (e.g. https://atech.deployhq.com): https://atech.deployhq.com
Username or e-mail address: adamw
API key (You can find this in Settings -> Security): my-api-key
Default project to use (please use permalink from web URL): my-project-permalink
File written to ./Deployfile

The CLI client will always look for the details of the current project in a file called Deployfile in the current directory. This file will contain your account URL, project permalink, username and API key, in JSON format.

It is recommended each member of your team has their own Deployfile, since the username and API key are user specific.

List servers (deployhq servers)

$ deployhq servers
Ungrouped Servers
              Name : Test
              Type : SSH
              Path : htdocs
            Branch : master
  Current Revision : baa7690059283c6e2e3d21fd0149f12b318175dd
          Hostname : localhost:22

Make a deployment (deployhq deploy)

$ deployhq deploy
1. Test (branch: master) (currently: baa7690059283c6e2e3d21fd0149f12b318175dd)
2. List Server Details
Please choose a server or group to deploy to:
1
Waiting for an available deployment slot...
Checking access to repository
Checking start and end revisions are valid
Checking connection to server Test
Updating repository from https://github.com/robertlyall/my-react-project.git
Getting information for start commit baa769
Getting information for end commit baa769
Checking out working copy of your repository at baa769
Deployment has finished successfully!

Usage Examples

Setting Up a New Project

When you first clone a project repository, set up the CLI configuration:

$ cd /path/to/my-project
$ deployhq configure
Account Domain (e.g. https://atech.deployhq.com): https://mycompany.deployhq.com
Username or e-mail address: dev@mycompany.com
API key (You can find this in Settings -> Security): abc123def456...
Default project to use (please use permalink from web URL): my-web-app
File written to ./Deployfile

The Deployfile should be added to your .gitignore since it contains your personal API credentials.

Checking Server Status Before Deployment

Before deploying, check which servers are available and their current deployment status:

$ deployhq servers
Production Servers
              Name : Production Web
              Type : SSH
              Path : /var/www/html
            Branch : main
  Current Revision : a1b2c3d4e5f6g7h8i9j0
          Hostname : web-prod-01.example.com:22

Staging Servers
              Name : Staging Web
              Type : SSH
              Path : /var/www/staging
            Branch : develop
  Current Revision : z9y8x7w6v5u4t3s2r1q0
          Hostname : web-staging-01.example.com:22

Deploying to a Specific Server

When you run deployhq deploy, you'll be presented with a list of available servers and groups:

$ deployhq deploy
1. Production Web (branch: main) (currently: a1b2c3d4e5f6g7h8i9j0)
2. Staging Web (branch: develop) (currently: z9y8x7w6v5u4t3s2r1q0)
3. Production Server Group
4. List Server Details
Please choose a server or group to deploy to: 2

Waiting for an available deployment slot...
Starting deployment to Staging Web...
Deployment queued successfully!

Quick Deployment Workflow

A typical deployment workflow using the CLI:

# 1. Navigate to your project directory
$ cd /path/to/my-project

# 2. Make sure you're on the correct branch
$ git checkout main
$ git pull origin main

# 3. Check current server status
$ deployhq servers

# 4. Start the deployment
$ deployhq deploy
# Select your target server when prompted

# 5. Monitor deployment in the web interface
# The CLI will confirm the deployment was queued

Working with Multiple Projects

If you work with multiple projects, each project directory should have its own Deployfile:

# Project A
$ cd /path/to/project-a
$ deployhq configure
# Enter credentials and select project A
$ deployhq deploy

# Project B
$ cd /path/to/project-b
$ deployhq configure
# Enter credentials and select project B
$ deployhq deploy

Frequently Asked Questions

Where do I find my API key?

Your API key can be found in your DeployHQ account under Settings > Security. Each team member should use their own API key rather than sharing credentials.

Can I automate deployments with the CLI?

While the CLI supports interactive deployments, for automation you should use the DeployHQ API directly. The CLI is designed for manual deployments from the command line.

Why isn't the Deployfile being committed to my repository?

The Deployfile contains your personal API credentials and should not be committed to version control. Add it to your .gitignore file:

echo "Deployfile" >> .gitignore

Each team member should create their own Deployfile with their own credentials.

Can I deploy to multiple servers at once?

Yes, you can deploy to a server group. When you run deployhq deploy, select a server group option to deploy to all servers in that group simultaneously.

How do I update the CLI to the latest version?

Update the gem using:

$ gem update deployhq

You can check your current version with:

$ gem list deployhq

What Ruby versions are supported?

The CLI requires Ruby 2.7.8 or later. You can check your Ruby version with:

$ ruby --version

Can I see deployment logs in the CLI?

Currently, the CLI confirms when a deployment is queued but doesn't stream deployment logs. To view detailed deployment logs, use the DeployHQ web interface or API.

The CLI says "command not found"

Make sure the gem is installed correctly and that your gem binary directory is in your PATH. You may need to restart your terminal after installation.

If you installed the gem with gem install deployhq, try:

$ gem environment

Check that the EXECUTABLE DIRECTORY is in your system PATH.

Can I use the CLI with CI/CD pipelines?

The CLI is interactive and prompts for user input, making it unsuitable for CI/CD automation. For automated deployments in CI/CD pipelines, use the DeployHQ API instead.

How do I switch between different DeployHQ accounts?

The Deployfile in each project directory can point to different accounts. Simply run deployhq configure in each project and specify the appropriate account domain, credentials, and project.

What permissions does my user account need?

Your DeployHQ user account needs: - Read access to view projects and servers - Deployment permissions to create deployments - The specific permissions depend on your team's access control settings

Is the CLI secure?

The CLI stores credentials in a local Deployfile. Keep this file secure and never commit it to version control. All API communication is done over HTTPS. Each team member should use their own API key for accountability.

Additional Resources