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

```bash
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

```bash
dhq auth status
```

This shows whether you are authenticated and which account you are connected to.

### Viewing Your API Token

```bash
dhq auth token
```

### Logging Out

```bash
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:

```bash
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](https://www.deployhq.com/support/cli/cli-ci-cd) for complete pipeline examples.

## Command-Line Flags

You can also pass credentials directly as flags on any command:

```bash
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](https://www.deployhq.com/support/cli/cli-configuration))
- Switch between accounts by setting environment variables
- Pass `--account` flags per command