cleveragents-core/docs/reference/config_cli.md

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.

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

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.

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

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.