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):
- CLI flags (
--account,--project, etc.) - Environment variables (
DEPLOYHQ_ACCOUNT,DEPLOYHQ_PROJECT, etc.) - Project config (
.deployhq.tomlin the current directory) - 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 projectcommand to link the folder yourself. dhq projects createnever replaces an existing.deployhq.tomlthat names a different project or account; it warns you and shows the commands to link the project manually.dhq launchdoes overwrite the file with the project, server and target it just used.- Pass
--no-savetodhq projects createto skip writing the file. - If a project with the same name already exists,
dhq projects createasks 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.