checkmate-cli 0.4.1

# Configuration Guide

Checkmate uses a hierarchical configuration system.

## Configuration Hierarchy

From lowest to highest priority:

1. **Built-in defaults**
2. **User config**: `~/.config/checkmate/config.toml`
3. **Project config**: `.checkmate/config.toml`
4. **Environment variables**: `CM_*`

Higher priority sources override lower ones.

## Project Configuration

Created by `cm init` at `.checkmate/config.toml`:

```toml
[env]
base_url = "http://localhost:8080"
timeout_ms = 5000

[defaults]
fail_fast = false
expect_status = 200
```

### env Section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `base_url` | string | - | API base URL (prepended to endpoints) |
| `timeout_ms` | integer | 5000 | HTTP request timeout in milliseconds |

### defaults Section

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `fail_fast` | boolean | false | Stop on first assertion failure |
| `expect_status` | integer | 200 | Default expected HTTP status |

## User Configuration

Optional user-level config at `~/.config/checkmate/config.toml`:

```toml
[env]
timeout_ms = 10000

[defaults]
fail_fast = true
```

Useful for personal preferences across all projects.

## Environment Variables

Override any setting with `CM_` prefix.

### Syntax

Use double underscore (`__`) for nested keys:

```bash
CM_ENV__BASE_URL="http://staging:8080"
CM_ENV__TIMEOUT_MS=10000
CM_DEFAULTS__FAIL_FAST=true
CM_DEFAULTS__EXPECT_STATUS=201
```

### Examples

```bash
# Run against staging
CM_ENV__BASE_URL="http://staging:8080" cm test run

# Longer timeout for slow endpoints
CM_ENV__TIMEOUT_MS=30000 cm test run

# Stop on first failure
CM_DEFAULTS__FAIL_FAST=true cm test run

# Combine multiple
CM_ENV__BASE_URL="http://staging:8080" \
CM_ENV__TIMEOUT_MS=10000 \
cm test run
```

### In CI/CD

```yaml
# GitHub Actions
env:
  CM_ENV__BASE_URL: ${{ secrets.API_URL }}
  CM_ENV__TIMEOUT_MS: "30000"

steps:
  - run: cm test run
```

## Viewing Configuration

### Show Current Config

```bash
cm config show
```

Output:
```toml
[env]
base_url = "http://localhost:8080"
timeout_ms = 5000

[defaults]
fail_fast = false
expect_status = 200
```

### Show as JSON

```bash
cm config show --json
```

### Show Sources

See which config files are loaded:

```bash
cm config sources
```

Output:
```
Configuration sources (in priority order):

  [ ] User:    /home/user/.config/checkmate/config.toml (not found)
  [✓] Project: /path/to/project/.checkmate/config.toml

  Environment variables: CM_* (e.g., CM_ENV__BASE_URL)
```

## Spec-Level Overrides

Test specs can override configuration:

```yaml
name: "Special Tests"

env:
  base_url: "http://different-server:8080"
  timeout_ms: 30000

tests:
  slow_endpoint:
    endpoint: /api/slow
    timeout_ms: 60000  # Test-specific override
```

Priority: test > spec > env > project > user > defaults

## Common Configurations

### Development

`.checkmate/config.toml`:
```toml
[env]
base_url = "http://localhost:8080"
timeout_ms = 5000

[defaults]
fail_fast = true
```

### CI/CD

Environment variables:
```bash
CM_ENV__BASE_URL="http://api-service:8080"
CM_ENV__TIMEOUT_MS=30000
CM_DEFAULTS__FAIL_FAST=false
```

### Staging

User config for staging testing:
```toml
[env]
base_url = "https://staging.api.example.com"
timeout_ms = 10000
```

## Best Practices

### 1. Project Config for Team Defaults

Commit `.checkmate/config.toml` with sensible defaults:

```toml
[env]
base_url = "http://localhost:8080"
timeout_ms = 5000
```

### 2. Environment Variables for Deployment

Don't hardcode production URLs in config files:

```bash
CM_ENV__BASE_URL="$API_URL" cm test run
```

### 3. User Config for Personal Preferences

Keep personal settings out of project:

```toml
# ~/.config/checkmate/config.toml
[defaults]
fail_fast = true  # Personal preference
```

### 4. Spec Overrides for Special Cases

Use sparingly for tests with unique requirements:

```yaml
env:
  timeout_ms: 60000  # This endpoint is slow
```

## Troubleshooting

### Config Not Applied

1. Check source priority: `cm config sources`
2. Verify file syntax: valid TOML
3. Check env var syntax: `CM_SECTION__KEY`

### Wrong Base URL

```bash
# See current config
cm config show

# Check if env var is set
echo $CM_ENV__BASE_URL
```

### Timeout Issues

```bash
# Increase timeout
CM_ENV__TIMEOUT_MS=30000 cm test run -v
```

---

## See Also

- [CLI Reference](CLI_REFERENCE.md) - Config commands
- [Quick Start](QUICKSTART.md) - Getting started