Last updated on 5th November 2026

CLI Configuration

The DeployHQ CLI uses a 4-layer configuration system that lets you set defaults at different levels -- from global account settings down to per-command flags.

Configuration Precedence

Configuration is resolved in this order (highest to lowest precedence):

  1. CLI flags (--account, --project, etc.)
  2. Environment variables (DEPLOYHQ_ACCOUNT, DEPLOYHQ_PROJECT, etc.)
  3. Project config (.deployhq.toml in the current directory)
  4. Global config (~/.deployhq/config.toml)

Interactive Setup

The easiest way to configure a project is the interactive wizard:

dhq configure

This walks you through selecting your account, project, and default server, then writes a .deployhq.toml file in the current directory.

Project Configuration

Each project directory can have a .deployhq.toml file that sets defaults for that project:

project = "my-app"

This means you can run dhq deploy without specifying --project every time.

Creating a Project Config

# Interactive
dhq configure

# Or manually
dhq config init
dhq config set project my-app

# Create the project config with values in one step
dhq config init --project my-app --account mycompany

Projects Created by the CLI

When you create a project with dhq projects create or dhq launch, the CLI saves it to a .deployhq.toml file in the current directory, together with the account it was created in, so later commands in that folder use it automatically. A few things to know:

  • The file is only written inside a git repository. Elsewhere (for example your home folder) nothing is saved, and the CLI prints the dhq config set project command to link the folder yourself.
  • dhq projects create never replaces an existing .deployhq.toml that names a different project or account; it warns you and shows the commands to link the project manually. dhq launch does overwrite the file with the project, server and target it just used.
  • Pass --no-save to dhq projects create to skip writing the file.
  • If a project with the same name already exists, dhq projects create asks first. In non-interactive mode it fails unless you pass --allow-duplicate.

Viewing Current Configuration

# Show current values
dhq config show

# Show values with their source (flag, env, file, etc.)
dhq config show --resolved

Setting and Unsetting Values

dhq config set project my-app
dhq config set account mycompany
dhq config unset project

Add --global to config init, config set, or config unset to work on the global config file instead of the one in the current directory:

dhq config init --global --account mycompany
dhq config set --global account mycompany
dhq config unset --global account

Adding to .gitignore

If your .deployhq.toml contains only the project permalink, it is safe to commit. If it contains credentials (not recommended), add it to .gitignore:

echo ".deployhq.toml" >> .gitignore

Global Configuration

Account-wide defaults are stored in ~/.deployhq/config.toml:

account = "mycompany"

This is useful when you work with a single DeployHQ account across multiple projects.

Environment Variables

All configuration values can be set via environment variables:

Variable Description Example
DEPLOYHQ_ACCOUNT Account subdomain mycompany
DEPLOYHQ_EMAIL Login email dev@mycompany.com
DEPLOYHQ_API_KEY API key abc123...
DEPLOYHQ_PROJECT Default project permalink my-app
DEPLOYHQ_AGENT Agent identifier (for automation) github-actions
DEPLOYHQ_OUTPUT_FILE Path for JSONL operation log /tmp/deployhq.jsonl

Environment variables take precedence over config files but are overridden by CLI flags.

Working with Multiple Projects

Different Projects in Different Directories

Place a .deployhq.toml in each project directory:

# Project A
cd /path/to/project-a
dhq configure    # sets project = "project-a"

# Project B
cd /path/to/project-b
dhq configure    # sets project = "project-b"

Override with Flags

You can always override the configured project with the --project or -p flag:

dhq servers list -p other-project

Working with Multiple Accounts

Per-Directory Configuration

Each .deployhq.toml can specify a different account:

account = "company-a"
project = "app-one"

Environment Variable Switching

For quick account switching in the same terminal:

export DEPLOYHQ_ACCOUNT=company-b
dhq projects list

Configuration Files Reference

File Location Scope
.deployhq.toml Current directory Per-project defaults
~/.deployhq/config.toml Home directory Global defaults

Both files use TOML format.