CLI Authentication
The DeployHQ CLI supports multiple authentication methods for different use cases -- interactive login for daily use, and environment variables for CI/CD pipelines and automation.
Interactive Login
The recommended method for local development. Credentials are stored securely in your operating system's keyring (macOS Keychain, Linux Secret Service, or Windows Credential Manager).
dhq auth login
You will be prompted for:
- Account: Your DeployHQ account subdomain (e.g. mycompany from https://mycompany.deployhq.com)
- Email: Your DeployHQ login email
- API Key: Found in Settings > Developers in your DeployHQ account (typed hidden)
If you leave the account empty, you are asked for it again.
Checking Authentication Status
dhq auth status
This shows whether you are authenticated and which account you are connected to.
Viewing Your API Token
dhq auth token
Logging Out
dhq auth logout
This removes credentials from your OS keyring. If you are logged in to more than one account, a picker lets you choose which one to remove. To remove the credentials for every account at once:
dhq auth logout --all
Signing Up from the Terminal
If you do not have a DeployHQ account yet, you can create one without leaving the terminal:
dhq signup
You are asked to accept the Terms of Service and your credentials are saved automatically. Afterwards, open the verification link DeployHQ emails you -- until your email address is verified, DeployHQ refuses API requests. Optional flags --full-name and --account-name set your name and account subdomain (the subdomain is generated if omitted).
Signing up switches the CLI to your new account, just as dhq auth login does. If the DEPLOYHQ_ACCOUNT environment variable or the .deployhq.toml in the current folder (or a parent folder) still names a different account, the CLI keeps using that one and warns you: unset the variable, or change or remove the account line in .deployhq.toml, to use the new account. The next steps it suggests are for once you have verified your email address.
Without a terminal, such as in a script, dhq signup also needs --email and --password, plus --accept-terms to confirm that the person creating the account has read and accepted the Terms of Service. Passing a password on the command line exposes it to your shell history and process list, so prefer running dhq signup interactively.
If an AI agent is helping you, run dhq auth login or dhq signup yourself in a separate terminal window rather than giving the agent your API key or password. Do not run them through the agent's ! shortcut either: a command run that way has no terminal to prompt in, so dhq cannot ask for the key or password and stops.
When dhq signup cannot prompt (non-interactive mode, such as when an agent runs it), it does not ask for a password on the command line: it stops and says that signing up needs you at the keyboard, and to run dhq signup yourself in a separate terminal window.
When You Are Not Signed In
If a command needs credentials and none are set, the CLI tells you to run dhq auth login in a separate terminal window, or dhq signup if you do not have a DeployHQ account yet. dhq auth status and dhq doctor give the same guidance. These messages also tell an AI agent to read DeployHQ's setup steps with dhq skills show and follow them.
Environment Variables
For CI/CD pipelines, scripts, and automation where interactive login is not possible, use environment variables:
export DEPLOYHQ_ACCOUNT=mycompany
export DEPLOYHQ_EMAIL=dev@mycompany.com
export DEPLOYHQ_API_KEY=your-api-key-here
When these environment variables are set, the CLI uses them automatically without requiring dhq auth login.
See CI/CD Integration for complete pipeline examples.
Command-Line Flags
You can also pass credentials directly as flags on any command:
dhq projects list --account mycompany --email dev@mycompany.com --api-key your-api-key
This is useful for one-off commands but not recommended for regular use since the API key may appear in shell history.
Authentication Precedence
The CLI resolves credentials in this order (highest to lowest precedence):
- Command-line flags (
--account,--email,--api-key) - Environment variables (
DEPLOYHQ_ACCOUNT,DEPLOYHQ_EMAIL,DEPLOYHQ_API_KEY) - Project config (
.deployhq.tomlin the current directory) - Global config (
~/.deployhq/config.toml) - OS keyring (from
dhq auth login)
Finding Your API Key
- Log in to your DeployHQ account at
https://your-account.deployhq.com - Go to Settings > Developers
- Your API keys are listed on this page. Create a new key if you don't have one yet.
Each team member should use their own API key for accountability and audit purposes.
Security Best Practices
- Use
dhq auth loginfor local development -- credentials are stored in your OS keyring, not in plain text files. - Use environment variables for CI/CD -- set them as secrets in your CI provider (GitHub Actions secrets, GitLab CI variables, etc.).
- Never commit credentials -- add
.deployhq.tomlto your.gitignoreif it contains sensitive values. - Use individual API keys -- each team member should authenticate with their own credentials.
- Rotate API keys regularly -- regenerate your API key from Settings > Developers if you suspect it has been compromised.
Troubleshooting
"Authentication failed" Errors
- Verify your email and API key are correct
- Check that your API key is active in Settings > Developers
- API access is included on every plan; if requests are rejected with
api_access_restricted, contact support - Try logging in to the DeployHQ web interface with the same credentials
Keyring Not Available
If your system does not have a keyring service (e.g. headless Linux servers), the CLI falls back to file-based credential storage. For CI/CD environments, use environment variables instead.
Multiple Accounts
If you work with multiple DeployHQ accounts, you can:
- Use different
.deployhq.tomlfiles in different project directories (see Configuration) - Switch between accounts by setting environment variables
- Pass
--accountflags per command