139 lines
3.8 KiB
Markdown
139 lines
3.8 KiB
Markdown
# 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.
|