# Config CLI Reference

The `agents config` command group manages CleverAgents runtime configuration
stored in a TOML file at `~/.cleveragents/config.toml`.

## Commands

### `agents config set <KEY> <VALUE>`

Set a configuration value.

| Parameter | Type       | Description                       |
|-----------|------------|-----------------------------------|
| `KEY`     | positional | Configuration key (dot-path)      |
| `VALUE`   | positional | Value to set                      |
| `--format`| option     | Output format (default: `rich`)   |

**Returns:** key, value, previous value, source, scope.

```bash
# Set log level
agents config set log_level DEBUG

# Dot-path aliases are accepted
agents config set server.port 9090
```

### `agents config get <KEY>`

Get a configuration value with its resolution chain.

| Parameter | Type       | Description                       |
|-----------|------------|-----------------------------------|
| `KEY`     | positional | Configuration key (dot-path)      |
| `--format`| option     | Output format (default: `rich`)   |

**Returns:** key, value, source, type, resolution chain.

The resolution chain shows which source the value was resolved from,
in priority order:

1. **CLI flag** (highest priority)
2. **Environment variable** (`CLEVERAGENTS_<KEY>`)
3. **Config file** (`~/.cleveragents/config.toml`)
4. **Default** (built-in default)

```bash
agents config get log_level
agents config get server_port --format json
```

### `agents config list [REGEX]`

List all configuration values with optional filtering.

| Parameter         | Type       | Description                       |
|-------------------|------------|-----------------------------------|
| `REGEX`           | positional | Optional regex filter for keys    |
| `--filter-values` | option     | Regex filter for values           |
| `--show-secrets`  | flag       | Reveal secret values (default: masked) |
| `--format`        | option     | Output format (default: `rich`)   |

**Returns:** array of settings with key, value, source, modified flag.

```bash
# List all settings
agents config list

# Filter by key pattern
agents config list "log.*"

# Filter by value
agents config list --filter-values "DEBUG"

# Show secret values
agents config list --show-secrets

# JSON output
agents config list --format json
```

## Key Format

Keys correspond to `Settings` field names. Both underscore and dot-path
notation are supported:

| Settings field    | Accepted keys                     |
|-------------------|-----------------------------------|
| `log_level`       | `log_level`, `log.level`          |
| `server_port`     | `server_port`, `server.port`      |
| `debug_enabled`   | `debug_enabled`, `debug.enabled`  |

## Config File

Configuration is stored in TOML format at:

```
~/.cleveragents/config.toml
```

Parent directories are created automatically when setting values.
The file uses [tomlkit](https://github.com/sdispater/tomlkit) for
writing, which preserves comments and formatting.

## Secret Masking

Keys containing any of the following patterns are treated as secrets
and masked with `****` in `config list` output:

- `api_key` / `api-key`
- `token`
- `secret`
- `password`

Use `--show-secrets` to reveal masked values:

```bash
agents config list --show-secrets
```

## Error Handling

| Error               | Cause                                  |
|---------------------|----------------------------------------|
| Unknown key         | Key not found in Settings model        |
| Invalid regex       | Malformed regex in filter or argument  |

## Environment Variables

Each configuration key maps to an environment variable with the
`CLEVERAGENTS_` prefix:

```
log_level    → CLEVERAGENTS_LOG_LEVEL
server_port  → CLEVERAGENTS_SERVER_PORT
```

Environment variables take precedence over config file values.