Using the DeployHQ CLI


With DeployHQ, you can deploy to your servers in several different ways. Most commonly, customers set up automatic deployments to trigger deployments on push to their repository host, deploy manually via the web interface or mobile app, or schedule deployments via either method.

As well as these methods, we also offer a handy CLI tool, allowing you to run deployments when you want without having to leave your terminal.


Getting started with the CLI tool is easy. You'll need Ruby installed on your system to be able to use the DeployHQ CLI. You can find some guides for installing it on the main Ruby website.

Once you've installed Ruby, enter the following command in your terminal, in any directory, which will install the library globally.

gem install deployhq

Setting up the CLI tool

Once you've installed the gem, you'll need to head to your project folder in your terminal, then run deployhq configure to set up the connection to your project.

$ 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

As you'll see, 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.

Obtaining the correct configuration

You can obtain the necessary configuration within the DeployHQ web interface. An API key can be created within Settings -> Security, and the project permalink forms part of the url when you're viewing your project in DeployHQ. If the URL is https://my-account.deployhq.com/projects/my-project, the permalink will simply be my-project.

Using the tool

You can perform a number of commands using the CLI tool. Firstly, typing deployhq help will provide a list of possible commands that you can run:

$ deployhq help

Usage: deployhq [options] command

deploy       Start a new deployment
servers      List configured servers and server groups
configure        Create a new configuration file for this tool

Common Options:
    -c, --config path                Configuration file path
    -p, --project project            Project to operate on (default is read from project: in config file)
    -v, --version                    Shows Version
    -h, --help                       Displays Help

With the 3 most common being deploy, servers, and configure as we have entered previously.

Typing deployhq servers gives us a list of servers and server groups in the project:

$ deployhq servers

Ungrouped Servers
              Name : My FTP server
              Type : FTP
              Path : htdocs
            Branch : master
  Current Revision : 63fcc862fb28c58cc23c8a191e3631d9e56b0502
          Hostname : ftp.byethost14.com:21

              Name : My SSH server
              Type : SSH/SFTP
              Path :
            Branch : master
  Current Revision : 63fcc862fb28c58cc23c8a191e3631d9e56b0502
          Hostname :

Then you can run deployhq deploy to initiate a deployment.

$ deployhq deploy

1. My FTP server (branch: master) (currently: 76b27d4bdc691bd8565e84c62d0088b57fe1a5ef)
2. My SSH server (branch: master) (currently: 63fcc862fb28c58cc23c8a191e3631d9e56b0502)
3. List Server Details
Please choose a server or group to deploy to:
Waiting for an available deployment slot...
Checking access to repository
Checking start and end revisions are valid
Checking connection to server My FTP server
Updating repository from git@codebasehq.com:test/git/git.git
Getting information for start commit 76b27d
Getting information for end commit 63fcc8
Checking out working copy of your repository at 63fcc8
[My FTP server] Uploading testfile2
                | htdocs/testfile2
Deployment has finished successfully!

Type the appropriate option key for the server you want to deploy to, then you'll receive realtime updates in your terminal about the progress of the deployment.

That's it! You've now set up and deployed using our handy CLI tool. You can find out more information about the library and view the source code in the GitHub repository.

If you have any questions about this, or another aspect of the DeployHQ service, please get in touch.

A little bit about the author

I'm Adam W, or as everyone prefers to call me - Batman. I get a lot of satisfaction out of helping our customers and am committed to making their customer experience as positive as possible. When not offering support to our customers, you'll find me gaming, listening to music or running.

Proudly powered by Katapult. Running on 100% renewable energy.