Last updated on 18th November 2026

Managing Projects with the CLI

The DeployHQ CLI lets you manage all aspects of your projects, from creation to repository configuration.

Listing Projects

# List all projects (starred projects appear first)
dhq projects list

# JSON output
dhq projects list --json

# Selected fields only
dhq projects list --json name,permalink,zone

Viewing Project Details

dhq projects show my-app

This displays the project name, repository URL, branch, zone, and other configuration details.

Creating a Project

dhq projects create --name "My New App"

# With options
dhq projects create --name "My New App" --zone eu --template rails-template

If a project with the same name already exists, the CLI lists it and stops when running non-interactively (it asks you when running interactively) instead of creating a second one. Pass --allow-duplicate to create the project anyway:

dhq projects create --name "My New App" --allow-duplicate

Saving the Project to .deployhq.toml

When you create a project from inside a git repository, the CLI saves it to a .deployhq.toml file in the current directory, together with the account it was created in. Later commands run in that folder use the project automatically, so you can leave out -p. Nothing is saved if the file already names a different project, or if the folder is not inside a git repository (in that case the CLI prints the dhq config set project command to link the folder yourself).

To skip saving:

dhq projects create --name "My New App" --no-save

Updating a Project

dhq projects update -p my-app --name "My Renamed App"

Other settings you can change with projects update:

# Change the permalink or zone
dhq projects update -p my-app --permalink my-new-permalink
dhq projects update -p my-app --zone <zone-id>

# Scan nightly for changes that have not been deployed
dhq projects update -p my-app --check-undeployed-changes true

# Keep a .tar file for each deployment
dhq projects update -p my-app --store-artifacts true

# Notification settings
dhq projects update -p my-app --email-notify-on only_failures
dhq projects update -p my-app --notification-email team@example.com
dhq projects update -p my-app --notify-pusher

--email-notify-on accepts always, only_failures, or never. --notify-pusher notifies the person who pushed the commit on automatic deployments.

Deleting a Project

dhq projects delete -p my-app

Starring Projects

Toggle a project's starred status. Starred projects appear first in listings:

dhq projects star -p my-app

Project Insights

View deployment statistics and analytics for a project:

dhq projects insights -p my-app

Uploading Deploy Keys

Upload your project's SSH public key to GitHub or GitLab:

dhq projects upload-key -p my-app --key-file ~/.ssh/id_ed25519.pub

--key-file is the path to the public key file and is required. This simplifies the process of granting DeployHQ access to your repository.

Regenerating the Deploy Key

Generate a new SSH deploy key for the project:

dhq projects regenerate-key my-app

# Choose the key type (ED25519 or RSA)
dhq projects regenerate-key my-app --key-type ED25519

If you omit --key-type, the account default is used. After regenerating, remember to update the key wherever the old one was installed.

Undeployed Changes

List the commits that have not been deployed yet:

dhq projects undeployed-changes my-app

AI Summary of Changes

Generate an AI summary of the changes in a deployment:

# Summarize changes up to a revision
dhq projects ai-overview my-app --end-ref main

# Summarize a specific range
dhq projects ai-overview my-app --start-ref abc123 --end-ref def456

--end-ref is required. --start-ref defaults to the last deployed revision.

Applying Suggested Build Settings

Detect the framework of a local directory and add DeployHQ's suggested build settings to a project: build commands, excluded files (such as dependency folders), and build cache files.

# Preview what would be applied
dhq projects apply-suggestions -p my-app --dry-run

# Apply the suggestions
dhq projects apply-suggestions -p my-app

Pass a path to detect from a directory other than the current one. Only missing settings are added, so it is safe to re-run. Build commands are added only when the project has none yet, so an existing build pipeline is never changed.

Deployment Badge

Generate a deployment status badge for your README:

dhq projects badge -p my-app

Opening in Browser

Open the project dashboard in your default browser:

dhq open my-app

Repository Management

View and manage the repository connected to your project.

Viewing Repository Details

dhq repos show -p my-app

Setting Up a Repository

dhq repos create -p my-app --scm-type git --url git@github.com:user/repo.git --branch main

Updating Repository Settings

dhq repos update -p my-app --branch main

If the project has no repository yet, repos update fails and tells you to connect one with dhq repos create first.

When you pass --branch to repos create or repos update, the branch has to exist in the repository. If it does not, the command fails (exit code 1) and lists the repository's branches (up to 20). The repository is still connected: with an SSH URL DeployHQ saves it on another branch, which the message names; with an HTTPS URL it keeps the branch you gave. Pick the right one with dhq repos update -p my-app --branch <name>. Nothing is deployed. If the repository has no branches yet because nothing has been pushed to it, push a commit first and then set the branch.

Listing Branches

dhq repos branches -p my-app

Viewing Recent Commits

dhq repos commits -p my-app

Viewing a Commit

Show details for a specific commit:

dhq repos commit-info <ref> -p my-app

Getting the Latest Revision

dhq repos latest-revision -p my-app

Using Templates

Create a project from an existing template:

# List available templates
dhq templates list

# List public templates (optionally filtered by framework)
dhq templates public --framework rails

# Create a project from a template
dhq projects create --name "My App" --template my-template

See Utilities for more on template management.