> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# ironclaw config

> Manage IronClaw configuration settings

# ironclaw config

Manage application configuration settings. Settings are stored in the database (if available) or on disk, with environment variables taking precedence.

## Subcommands

* `init` - Generate a default config.toml file
* `list` - List all settings and their current values
* `get` - Get a specific setting value
* `set` - Set a setting value
* `reset` - Reset a setting to its default value
* `path` - Show settings storage info

## Settings Priority

Settings are resolved in this order (highest to lowest priority):

1. **Environment variables** - `AGENT_NAME=mybot`
2. **config.toml file** - `~/.ironclaw/config.toml`
3. **Database** - Settings table
4. **Defaults** - Built-in defaults

***

## ironclaw config init

Generate a default `config.toml` file with current settings.

### Syntax

```bash theme={null}
ironclaw config init [FLAGS]
```

### Flags

**`--output, -o <PATH>`**

Output path for the config file.

* Default: `~/.ironclaw/config.toml`

**`--force`**

Overwrite existing file.

### Examples

```bash theme={null}
# Generate config file in default location
ironclaw config init

# Generate in custom location
ironclaw config init --output /etc/ironclaw/config.toml

# Overwrite existing file
ironclaw config init --force
```

### Output

```bash theme={null}
Config file written to /Users/you/.ironclaw/config.toml

Edit the file to customize settings.
Priority: env var > config.toml > database > defaults
```

The generated file includes all settings with their current values, organized by category:

```toml theme={null}
[agent]
name = "ironclaw"
max_parallel_jobs = 3

[heartbeat]
interval_seconds = 300
enabled = true

[llm]
provider = "nearai"
model = "anthropic/claude-sonnet-4"
```

***

## ironclaw config list

List all settings and their current values.

### Syntax

```bash theme={null}
ironclaw config list [FLAGS]
```

### Flags

**`--filter, -f <PREFIX>`**

Show only settings matching this prefix.

### Examples

```bash theme={null}
# List all settings
ironclaw config list

# Filter by category
ironclaw config list --filter agent
ironclaw config list --filter heartbeat
ironclaw config list --filter llm
```

### Output

```bash theme={null}
Settings (source: database):

  agent.name                          ironclaw
  agent.max_parallel_jobs             3
  heartbeat.enabled                   true
  heartbeat.interval_seconds          300
  llm.provider                        nearai
  llm.model                           anthropic/claude-sonnet-4
  llm.max_tokens                      8192
```

Long values are truncated:

```bash theme={null}
  workspace.allowed_prefixes          ["/home/user/workspace", "/Users/user/proj...
```

***

## ironclaw config get

Get a specific setting value.

### Syntax

```bash theme={null}
ironclaw config get <PATH>
```

### Arguments

**`<PATH>`**

Setting path using dot notation (e.g., `agent.name`, `llm.model`).

### Examples

```bash theme={null}
# Get agent name
ironclaw config get agent.name
# Output: ironclaw

# Get LLM model
ironclaw config get llm.model
# Output: anthropic/claude-sonnet-4

# Get heartbeat interval
ironclaw config get heartbeat.interval_seconds
# Output: 300
```

### Error Handling

```bash theme={null}
ironclaw config get invalid.setting
# Error: Setting not found: invalid.setting
```

***

## ironclaw config set

Set a setting value.

### Syntax

```bash theme={null}
ironclaw config set <PATH> <VALUE>
```

### Arguments

**`<PATH>`**

Setting path using dot notation.

**`<VALUE>`**

Value to set. Can be a string, number, boolean, or JSON.

### Examples

```bash theme={null}
# Set agent name
ironclaw config set agent.name "my-assistant"
# Output: Set agent.name = my-assistant

# Set numeric value
ironclaw config set agent.max_parallel_jobs 5
# Output: Set agent.max_parallel_jobs = 5

# Set boolean
ironclaw config set heartbeat.enabled true
# Output: Set heartbeat.enabled = true

# Set JSON array
ironclaw config set workspace.allowed_prefixes '["~/workspace", "~/projects"]'
# Output: Set workspace.allowed_prefixes = ["~/workspace", "~/projects"]
```

### Requirements

* Requires database connection
* Setting path must exist in the schema
* Value must be valid for the setting type

### Error Handling

```bash theme={null}
ironclaw config set invalid.path "value"
# Error: Unknown setting: invalid.path

ironclaw config set agent.max_parallel_jobs "not-a-number"
# Error: Invalid value for agent.max_parallel_jobs: expected integer
```

***

## ironclaw config reset

Reset a setting to its default value.

### Syntax

```bash theme={null}
ironclaw config reset <PATH>
```

### Arguments

**`<PATH>`**

Setting path to reset.

### Examples

```bash theme={null}
# Reset agent name to default
ironclaw config reset agent.name
# Output: Reset agent.name to default: ironclaw

# Reset heartbeat interval
ironclaw config reset heartbeat.interval_seconds
# Output: Reset heartbeat.interval_seconds to default: 300
```

### Behavior

* Removes the setting from the database
* The default value will be used
* Environment variables and config.toml still take precedence

***

## ironclaw config path

Show settings storage information.

### Syntax

```bash theme={null}
ironclaw config path
```

### Output

```bash theme={null}
Settings stored in: database (settings table)
Env config:         /Users/you/workspace/.env
TOML config:        /Users/you/.ironclaw/config.toml (found)
```

If config.toml doesn't exist:

```bash theme={null}
Settings stored in: PostgreSQL (not connected, using defaults)
Env config:         /Users/you/workspace/.env
TOML config:        /Users/you/.ironclaw/config.toml (not found, run `ironclaw config init` to create)
```

## Common Settings

### Agent Settings

```bash theme={null}
agent.name                    # Agent display name
agent.max_parallel_jobs       # Maximum concurrent jobs
```

### Heartbeat Settings

```bash theme={null}
heartbeat.enabled             # Enable periodic heartbeat
heartbeat.interval_seconds    # Heartbeat interval
```

### LLM Settings

```bash theme={null}
llm.provider                  # LLM provider (nearai, anthropic, openai)
llm.model                     # Model identifier
llm.max_tokens                # Maximum tokens per request
llm.temperature               # Sampling temperature (0.0-1.0)
```

### Workspace Settings

```bash theme={null}
workspace.allowed_prefixes    # Allowed file path prefixes (JSON array)
```

## Configuration File Format

The `config.toml` file uses TOML format:

```toml theme={null}
# Agent configuration
[agent]
name = "ironclaw"
max_parallel_jobs = 3

# Heartbeat configuration
[heartbeat]
enabled = true
interval_seconds = 300

# LLM configuration
[llm]
provider = "nearai"
model = "anthropic/claude-sonnet-4"
max_tokens = 8192
temperature = 0.7

# Workspace configuration
[workspace]
allowed_prefixes = ["/home/user/workspace"]
```

## Troubleshooting

### "Database connection required"

`config set` and `config reset` require a database connection:

```bash theme={null}
# Check database
ironclaw doctor

# Verify DATABASE_URL or LIBSQL_PATH is set
env | grep DATABASE
```

### "Warning: Could not connect to database"

The command falls back to disk-based configuration. Settings will be read from defaults and config.toml only.

### Settings not taking effect

Remember the priority order:

1. Check environment variables: `env | grep -i <setting>`
2. Check config.toml: `cat ~/.ironclaw/config.toml`
3. Check database: `ironclaw config get <path>`

## Related Commands

* [onboard](/cli/onboard) - Initial configuration wizard
* [doctor](/cli/doctor) - Validate configuration