CLI Configuration

The llmist CLI is configured through TOML files and environment variables.

Configuration File

The CLI loads configuration from ~/.llmist/cli.toml:

    # Initialize with default config
    npx @llmist/cli init

Basic Structure

~/.llmist/cli.toml

[complete]
model = "anthropic:claude-sonnet-4-5"
temperature = 0.7

[agent]
model = "anthropic:claude-sonnet-4-5"
max-iterations = 15
gadget = ["~/gadgets/common-tools.ts"]

Inheritance

Sections can inherit settings from parent sections:

[agent]
model = "anthropic:claude-sonnet-4-5"
max-iterations = 15

[code-review]
inherits = "agent"
temperature = 0.3
system = "You are a code reviewer."

Custom Commands

Create custom commands with a type field:

[code-review]
type = "agent"
description = "Review code for bugs and best practices."
system = "You are a senior code reviewer."
max-iterations = 5
gadget = ["~/gadgets/code-tools.ts"]

Run with:

    npx @llmist/cli code-review "Review my PR"

Rate Limiting Configuration

Control proactive rate limiting to prevent API errors before they occur.

Global Rate Limits

Apply to all commands:

[rate-limits]
requests-per-minute = 50
tokens-per-minute = 40000
tokens-per-day = 1500000        # Optional daily cap
safety-margin = 0.8             # Start throttling at 80% of limit
enabled = true                  # Default: true if any limit is set

Per-Command Rate Limits

Override global settings for specific commands:

[agent.rate-limits]
requests-per-minute = 15        # More conservative for agent mode
tokens-per-minute = 100000

[complete.rate-limits]
requests-per-minute = 100       # Higher limits for completion
tokens-per-minute = 200000

Provider-Specific Examples

Gemini Free Tier:

[agent.rate-limits]
requests-per-minute = 15
tokens-per-minute = 1000000
tokens-per-day = 1500000

Anthropic Tier 1:

[agent.rate-limits]
requests-per-minute = 50
tokens-per-minute = 40000

OpenAI Free Tier:

[agent.rate-limits]
requests-per-minute = 3
tokens-per-minute = 40000

Disabling Rate Limiting

[rate-limits]
enabled = false

Or per-command:

[agent.rate-limits]
enabled = false

Retry Configuration

Control automatic retry behavior for transient failures.

Global Retry Settings

[retry]
enabled = true                  # Default: true
retries = 3                     # Max retry attempts
min-timeout = 1000             # Initial delay (ms)
max-timeout = 30000            # Maximum delay (ms)
factor = 2                     # Exponential backoff multiplier
randomize = true               # Add jitter to prevent thundering herd
respect-retry-after = true     # Honor Retry-After headers
max-retry-after-ms = 120000    # Cap server-requested delays (2 minutes)

Per-Command Retry Settings

[agent.retry]
retries = 5                    # More retries for long-running agents
max-timeout = 60000           # Up to 1 minute between retries

[complete.retry]
retries = 1                   # Fast-fail for completions
max-timeout = 5000

Configuration Precedence

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

1. CLI flags (--rate-limit-rpm, --max-retries, --no-retry, etc.)
2. Profile-specific TOML config ([agent.rate-limits], [complete.retry])
3. Global TOML config ([rate-limits], [retry])
4. Provider defaults (auto-detected from model)
5. Built-in defaults

CLI Flags

Override TOML configuration for individual runs:

Rate Limiting:

llmist agent "prompt" --rate-limit-rpm 50 --rate-limit-tpm 40000
llmist agent "prompt" --no-rate-limit

Retry:

llmist agent "prompt" --max-retries 5 --retry-max-timeout 60000
llmist agent "prompt" --no-retry

For complete flag documentation, run:

llmist agent --help
llmist complete --help

Prompt Templates

Define reusable prompts with Eta templating:

[prompts]
base-assistant = "You are a helpful AI assistant."
expert = """
<%~ include("@base-assistant") %>
You are also an expert in <%= it.field %>.
"""

[my-expert]
system = '<%~ include("@expert", {field: "TypeScript"}) %>'

File Includes

Load prompt content from external files with includeFile():

[prompts]
# Load entire prompt from file
from-file = '<%~ includeFile("~/.llmist/prompts/custom.md") %>'

# Mix file content with inline content
hybrid = """
<%~ include("@base-assistant") %>
<%~ includeFile("./prompts/project-rules.txt") %>
"""

[code-review]
system = '<%~ includeFile("~/.llmist/prompts/code-review.md") %>'

Path resolution:

• ~ expands to home directory
• Relative paths resolve from config file location
• Included files can themselves use includeFile() and include()
• Circular includes are detected and prevented

Gadget Approval

The gadget approval system provides a safety layer for potentially dangerous gadget executions.

Approval Modes

Mode	Behavior
allowed	Gadget executes immediately
denied	Gadget is rejected, LLM receives denial message
approval-required	User is prompted before execution

Default Behavior

By default, these gadgets require approval:

• RunCommand - Executes shell commands
• WriteFile - Creates or modifies files
• EditFile - Edits existing files

All other gadgets default to allowed.

Configuration

[agent]
gadget-approval = { WriteFile = "allowed", Shell = "denied", ReadFile = "allowed" }

Wildcard Default

Set default mode for all unconfigured gadgets:

[agent]
gadget-approval = { "*" = "denied", ReadFile = "allowed", FloppyDisk = "allowed" }

Example Configurations

High-Security Mode:

[agent]
gadget-approval = {
  WriteFile = "denied",
  EditFile = "denied",
  RunCommand = "denied",
  ReadFile = "allowed"
}

Trust All Mode:

[agent]
gadget-approval = { "*" = "allowed" }

Selective Approval:

[agent]
gadget-approval = {
  RunCommand = "approval-required",
  WriteFile = "allowed",
  DeleteFile = "denied"
}

Approval Prompts

For file operations, a colored diff is shown:

🔒 Approval required: Modify src/index.ts

--- src/index.ts (original)
+++ src/index.ts (modified)
@@ -1,3 +1,4 @@
 import { foo } from './foo';
+import { bar } from './bar';

   ⏎ approve, or type to reject:

• Press Enter or type y to approve
• Type any other text to reject (sent to LLM as feedback)

Non-Interactive Mode

When running non-interactively (e.g., in scripts or CI), approval-required gadgets are automatically denied.

Environment Variables

API Keys

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

Logging

export LLMIST_LOG_LEVEL="debug"   # silly, trace, debug, info, warn, error, fatal
export LLMIST_LOG_TEE="true"      # Also write to stdout when file logging is active

Session-Based Logging

Each CLI session automatically creates its own log directory at ~/.llmist/logs/<session-name>/ with a memorable name like sunny-falcon. Numbers are only appended when there’s a name collision (e.g., sunny-falcon-2). Session logs are stored in session.log.jsonl within that directory.

Global CLI Flags

These flags work with any command:

Flag	Description
--log-level <level>	Set log level
--version	Show version number
--help	Show help

MCP servers ([mcp.servers.<name>])

Configure Model Context Protocol servers that the agent should attach to. Each server is its own table.

The MCP config schema is strict: [mcp], [mcp.servers], each server block, and nested env / headers blocks must have the expected shape. Unknown keys and invalid values fail config validation with a path-specific error instead of silently dropping a server.

Stdio server

[mcp.servers.fs]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
# Optional:
# trust = true                  # bypass the runtime allowlist for this server
# enabled = false               # temporarily disable without removing the block
# timeout-ms = 30000            # per-call timeout
# env = { TZ = "UTC" }

Streamable HTTP server

[mcp.servers.remote]
transport = "http"
url = "https://my-mcp.example.com/mcp"

[mcp.servers.remote.headers]
Authorization = "Bearer xyz"

Field reference

Field	Required	Default	Notes
transport	yes	—	"stdio" or "http" (legacy SSE not supported)
command	stdio only	—	Executable; basename gated by allowlist unless trust = true
args	optional	[]	Arguments to the executable
env	optional	parent env	Environment overrides for the spawned child
url	http only	—	Must include http:// or https://
headers	optional	—	Fixed HTTP headers (e.g. Authorization)
trust	optional	false	Bypass the stdio command allowlist for this server
enabled	optional	true	Set false to skip the block at startup
timeout-ms	optional	none	Per-operation timeout in milliseconds; must be a non-negative integer, and 0 disables the timeout

Importing from Claude Code

If you already have MCP servers configured in ~/.claude.json (Claude Code, Cursor, Cline), pull them into your llmist config:

llmist mcp import-claude-code                  # emit blocks to stdout
llmist mcp import-claude-code >> ~/.llmist/config.toml
llmist mcp import-claude-code --write          # append directly to ~/.llmist/config.toml

Set CLAUDE_CONFIG_HOME to override the source path.

See Also

• MCP — library guide
• MCP security — STDIO allowlist
• CLI Reference - All CLI commands
• CLI Gadgets - Writing gadgets for CLI
• Logging - Detailed logging configuration