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:

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

```toml
project = "my-app"
```

This means you can run `dhq deploy` without specifying `--project` every time.

### Creating a Project Config

```bash
# Interactive
dhq configure

# Or manually
dhq config init
dhq config set project my-app
```

### Viewing Current Configuration

```bash
# Show current values
dhq config show

# Show values with their source (flag, env, file, etc.)
dhq config show --resolved
```

### Setting and Unsetting Values

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

```bash
echo ".deployhq.toml" >> .gitignore
```

## Global Configuration

Account-wide defaults are stored in `~/.deployhq/config.toml`:

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

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

```bash
dhq servers list -p other-project
```

## Working with Multiple Accounts

### Per-Directory Configuration

Each `.deployhq.toml` can specify a different account:

```toml
account = "company-a"
project = "app-one"
```

### Environment Variable Switching

For quick account switching in the same terminal:

```bash
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](https://toml.io) format.