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

[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):

CLI flags (--rate-limit-rpm, --max-retries, --no-retry, etc.)
Profile-specific TOML config ([agent.rate-limits], [complete.retry])
Global TOML config ([rate-limits], [retry])
Provider defaults (auto-detected from model)
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

Global CLI Flags

These flags work with any command:

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