Last updated on 4th April 2026

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 > Security in your DeployHQ account

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.

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):

  1. Command-line flags (--account, --email, --api-key)
  2. Environment variables (DEPLOYHQ_ACCOUNT, DEPLOYHQ_EMAIL, DEPLOYHQ_API_KEY)
  3. Project config (.deployhq.toml in the current directory)
  4. Global config (~/.deployhq/config.toml)
  5. OS keyring (from dhq auth login)

Finding Your API Key

  1. Log in to your DeployHQ account at https://your-account.deployhq.com
  2. Go to Settings > Security
  3. Your API key is displayed on this page

Each team member should use their own API key for accountability and audit purposes.

Security Best Practices

  • Use dhq auth login for 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.toml to your .gitignore if 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 > Security 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 > Security
  • Ensure your account has API access enabled on your plan
  • 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.toml files in different project directories (see Configuration)
  • Switch between accounts by setting environment variables
  • Pass --account flags per command