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

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

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:

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

Both files use TOML format.