term-llm

term-llm

A Swiss Army knife for your terminal—AI-powered commands, answers, and images at your fingertips.

Features

• Command suggestions: Natural language → executable shell commands
• Ask questions: Get answers with optional web search
• Chat mode: Persistent sessions with tool and MCP support
• File editing: Edit code with AI assistance (supports line ranges)
• File context: Include files, clipboard, stdin, or line ranges as context (-f)
• Image generation: Create and edit images (Gemini, OpenAI, xAI, Flux)
• MCP servers: Extend with external tools via Model Context Protocol
• Agents: Named configuration bundles for different workflows
• Skills: Portable instruction bundles for specialized tasks
• Multiple providers: Anthropic, OpenAI, ChatGPT, GitHub Copilot, xAI (Grok), OpenRouter, Gemini, Gemini CLI, Zen (free tier), Claude Code (claude-bin), Ollama, LM Studio
• Local LLMs: Run with Ollama, LM Studio, or any OpenAI-compatible server
• Free tier available: Try it out with Zen (no API key required)

$ term-llm exec "find all go files modified today"

> find . -name "*.go" -mtime 0   Uses find with name pattern
  fd -e go --changed-within 1d   Uses fd (faster alternative)
  find . -name "*.go" -newermt "today"   Alternative find syntax
  something else...

Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/samsaffron/term-llm/main/install.sh | sh

Or with options:

curl -fsSL https://raw.githubusercontent.com/samsaffron/term-llm/main/install.sh | sh -s -- --version v0.1.0 --install-dir ~/bin

Go install

go install github.com/samsaffron/term-llm@latest

Build from source

git clone https://github.com/samsaffron/term-llm
cd term-llm
go build

Setup

On first run, term-llm will prompt you to choose a provider (Anthropic, OpenAI, ChatGPT, GitHub Copilot, xAI, OpenRouter, Gemini, Gemini CLI, Zen, Claude Code (claude-bin), Ollama, or LM Studio).

Option 1: Try it free with Zen

OpenCode Zen provides free access to multiple models. No API key required:

term-llm exec --provider zen "list files"
term-llm ask --provider zen "explain git rebase"
term-llm ask --provider zen:gpt-5-nano "quick question"  # use specific model

Available free models: glm-4.7-free, minimax-m2.1-free, grok-code, big-pickle, gpt-5-nano

Or configure as default:

# In ~/.config/term-llm/config.yaml
default_provider: zen

Option 2: Use API key

Set your API key as an environment variable:

# For Anthropic (API key, or use OAuth — see below)
export ANTHROPIC_API_KEY=your-key

# For OpenAI
export OPENAI_API_KEY=your-key

# For xAI (Grok)
export XAI_API_KEY=your-key

# For OpenRouter
export OPENROUTER_API_KEY=your-key

# For Gemini
export GEMINI_API_KEY=your-key

Option 3: Use Anthropic with OAuth (Claude Pro/Max subscription)

If you have a Claude Pro or Max subscription and the Claude Code CLI installed, you can use OAuth instead of an API key:

term-llm ask --provider anthropic "explain this code"

On first interactive use, you'll be prompted to run claude setup-token and paste the resulting token. The token is saved to ~/.config/term-llm/anthropic_oauth.json and reused automatically.

You can also set the token via environment variable (useful for CI after generating a token interactively):

export CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token

Option 4: Use ChatGPT (Plus/Pro subscription)

If you have a ChatGPT Plus or Pro subscription, you can use the chatgpt provider with native OAuth authentication:

term-llm ask --provider chatgpt "explain this code"
term-llm ask --provider chatgpt:gpt-5.2-codex "code question"

On first use, you'll be prompted to authenticate via browser. Credentials are stored locally and refreshed automatically.

# In ~/.config/term-llm/config.yaml
default_provider: chatgpt

providers:
  chatgpt:
    model: gpt-5.2-codex

Option 5: Use xAI (Grok)

xAI provides access to Grok models with native web search and X (Twitter) search capabilities.

# In ~/.config/term-llm/config.yaml
default_provider: xai

providers:
  xai:
    model: grok-4-1-fast  # default model

Available models:

Model	Context	Description
grok-4-1-fast	2M	Latest, best for tool calling (default)
grok-4-1-fast-reasoning	2M	With chain-of-thought reasoning
grok-4-1-fast-non-reasoning	2M	Faster, no reasoning overhead
grok-4	256K	Base Grok 4 model
grok-3 / grok-3-fast	131K	Previous generation
grok-3-mini / grok-3-mini-fast	131K	Smaller, faster
grok-code-fast-1	256K	Optimized for coding tasks

Or use the --provider flag:

term-llm ask --provider xai "explain quantum computing"
term-llm ask --provider xai -s "latest xAI news"  # uses native web + X search
term-llm ask --provider xai:grok-4-1-fast-reasoning "solve this step by step"
term-llm ask --provider xai:grok-code-fast-1 "review this code"

Option 6: Use OpenRouter

OpenRouter provides a unified OpenAI-compatible API across many models. term-llm sends attribution headers by default.

# In ~/.config/term-llm/config.yaml
default_provider: openrouter

providers:
  openrouter:
    model: x-ai/grok-code-fast-1
    app_url: https://github.com/samsaffron/term-llm
    app_title: term-llm

Model Discovery

List available models from any supported provider:

term-llm models --provider anthropic  # List Anthropic models
term-llm models --provider openrouter # List OpenRouter models
term-llm models --provider ollama     # List local Ollama models
term-llm models --provider lmstudio   # List local LM Studio models
term-llm models --json                # Output as JSON

Provider Discovery

List all available LLM providers and their configuration status:

term-llm providers                 # List all providers
term-llm providers --configured    # Only show configured providers
term-llm providers --builtin       # Only show built-in providers
term-llm providers anthropic       # Show details for specific provider
term-llm providers --json          # JSON output

Option 7: Use local LLMs (Ollama, LM Studio)

Run models locally with Ollama or LM Studio:

# List available models from your local server
term-llm models --provider ollama
term-llm models --provider lmstudio

# Configure in ~/.config/term-llm/config.yaml

default_provider: ollama

providers:
  ollama:
    type: openai_compatible
    base_url: http://localhost:11434/v1
    model: llama3.2:latest

  lmstudio:
    type: openai_compatible
    base_url: http://localhost:1234/v1
    model: deepseek-coder-v2

For other OpenAI-compatible servers (vLLM, text-generation-inference, etc.):

providers:
  my-server:
    type: openai_compatible
    base_url: http://your-server:8080/v1
    model: mixtral-8x7b
    models:  # optional: list models for shell autocomplete
      - mixtral-8x7b
      - llama-3-70b

The models list enables tab completion for --provider my-server:<TAB>. The configured model is always included in completions.

Option 8: Use Claude Code (claude-bin)

If you have Claude Code installed and logged in, you can use the claude-bin provider to run completions via the Claude Agent SDK. This requires no API key - it uses Claude Code's existing authentication.

# Use directly via --provider flag (no config needed)
term-llm ask --provider claude-bin "explain this code"
term-llm ask --provider claude-bin:haiku "quick question"  # use haiku model
term-llm exec --provider claude-bin "list files"           # command suggestions
term-llm ask --provider claude-bin -s "latest news"        # with web search

# Or configure as default

# In ~/.config/term-llm/config.yaml
default_provider: claude-bin

providers:
  claude-bin:
    model: sonnet  # opus, sonnet, or haiku

Features:

• No API key required - uses Claude Code's OAuth authentication
• Full tool support via MCP (exec, search, edit all work)
• Model selection: opus, sonnet (default), haiku
• Works immediately if Claude Code is installed and logged in

Option 9: Use existing CLI credentials (gemini-cli)

If you have gemini-cli installed and logged in, term-llm can use those credentials directly:

# Use gemini-cli credentials (no config needed)
term-llm ask --provider gemini-cli "explain this code"

Or configure as default:

# In ~/.config/term-llm/config.yaml
default_provider: gemini-cli  # uses ~/.gemini/oauth_creds.json

OpenAI-compatible providers support two URL options:

• base_url: Base URL (e.g., https://api.cerebras.ai/v1) - /chat/completions is appended automatically
• url: Full URL (e.g., https://api.cerebras.ai/v1/chat/completions) - used as-is without appending

Use url when your endpoint doesn't follow the standard /chat/completions path, or to paste URLs directly from API documentation.

Option 10: Use GitHub Copilot

If you have GitHub Copilot (free, Individual, or Business), you can use the copilot provider with OAuth device flow authentication:

term-llm ask --provider copilot "explain this code"
term-llm ask --provider copilot:claude-opus-4.5 "complex question"

On first use, you'll be prompted to authenticate via GitHub device flow. Credentials are stored locally and refreshed automatically.

# In ~/.config/term-llm/config.yaml
default_provider: copilot

providers:
  copilot:
    model: gpt-4.1  # free tier, or gpt-5.2-codex for paid

Available models:

Model	Description
gpt-4.1	Default, works on free tier
gpt-5.2-codex	Advanced coding model (paid)
gpt-5.1	GPT-5.1 (paid)
claude-opus-4.5	Claude Opus 4.5 via Copilot (paid)
gemini-3-pro	Gemini 3 Pro via Copilot (paid)
grok-code-fast-1	Grok coding model via Copilot (paid)

Features:

• Free tier with GPT-4.1 (no Copilot subscription required, just GitHub account)
• OAuth device flow authentication (no API key needed)
• Full tool support via MCP

Usage

term-llm exec "your request here"

Use arrow keys to select a command, Enter to execute, or press h for detailed help on the highlighted command. Select "something else..." to refine your request.

Use term-llm chat for a persistent session.

term-llm chat

Using Agents

Use the @agent prefix syntax to use a specific agent:

term-llm ask @reviewer "review this code"     # use reviewer agent
term-llm chat @coder                          # start chat with coder agent
term-llm loop @researcher --done-file ...     # use researcher agent in loop
term-llm exec @bash-expert "find large files" # use bash-expert agent

See Agents for more details on creating and managing agents.

Chat Keyboard Shortcuts

Key	Action
Enter	Send message
Ctrl+J or Alt+Enter	Insert newline
Ctrl+C	Quit
Ctrl+K	Clear conversation
Ctrl+S	Toggle web search
Ctrl+P	Command palette
Ctrl+T	MCP server picker
Ctrl+L	Switch model
Ctrl+N	New session
Ctrl+F	Attach file
Ctrl+O	Conversation inspector
Esc	Cancel streaming

Chat Slash Commands

Command	Description
/help	Show help
/clear	Clear conversation
/model	Show current model
/search	Toggle web search
/mcp	Manage MCP servers
/quit	Exit chat

Flags

Flag	Short	Description
--provider		Override provider, optionally with model (e.g., openai:gpt-5.2)
--file	-f	File(s) to include as context (supports globs, line ranges, 'clipboard')
--auto-pick	-a	Auto-execute the best suggestion without prompting (exec only)
--agent	-a	Use a specific agent (ask/chat only; see also @agent syntax)
--skills		Skills mode: all, none, or comma-separated names
--max N	-n N	Limit to N options in the selection UI
--search	-s	Enable web search (configurable: Exa, Brave, Google, DuckDuckGo) and page reading
--native-search		Use provider's native search (override config)
--no-native-search		Force external search tools instead of native
--print-only	-p	Print the command instead of executing it
--debug	-d	Show provider debug information
--debug-raw		Emit raw debug logs with timestamps (tool calls/results, raw requests)
--system-message	-m	Custom system message/instructions
--stats		Show session statistics (time, tokens, tool calls)
--max-turns		Max agentic turns for tool execution (default: 20 for exec, 200 for chat)
--yolo		Auto-approve all tool operations (for unattended runs)

Note: The -a short flag has different meanings:

• In exec: -a is --auto-pick (auto-execute best suggestion)
• In ask/chat: -a is --agent (use a specific agent)

Examples

term-llm exec "list files by size"              # interactive selection
term-llm exec "compress folder" --auto-pick     # auto-execute best
term-llm exec "find large files" -n 3           # show max 3 options
term-llm exec "install latest node" -s          # with web search
term-llm exec "disk usage" -p                   # print only
term-llm exec --provider zen "git status"       # use specific provider
term-llm exec --provider openai:gpt-5.2 "list"   # provider with specific model
term-llm exec --debug-raw "list files"          # raw debug logs with timestamps
term-llm exec --provider ollama:llama3.2 "list" # use local Ollama model
term-llm exec --provider lmstudio:deepseek "list"  # use LM Studio model
term-llm ask --provider openai:gpt-5.2-xhigh "complex question"  # max reasoning
term-llm exec --provider openai:gpt-5.2-low "quick task"         # faster/cheaper

# With file context
term-llm exec -f error.log "find the cause"     # analyze a file
term-llm exec -f "*.go" "run tests for these"   # glob pattern
git diff | term-llm exec "commit message"       # pipe stdin

# Ask a question
term-llm ask "What is the difference between TCP and UDP?"
term-llm ask "latest node.js version" -s        # with web search
term-llm ask --provider zen "explain docker"    # use specific provider
term-llm ask -f code.go "explain this code"     # with file context
term-llm ask -f code.go:50-100 "explain this function"  # specific lines
term-llm ask -f clipboard "what is this?"       # from clipboard
cat README.md | term-llm ask "summarize this"   # pipe stdin
term-llm ask --debug-raw "latest zig release"   # raw debug logs with timestamps

# Edit files
term-llm edit "add error handling" -f main.go
term-llm edit "refactor loop" -f utils.go:20-40  # only lines 20-40
term-llm edit "add tests" -f "*.go" --dry-run    # preview changes
term-llm edit "use the API" -f main.go -c api/client.go  # with context

# Generate images
term-llm image "a sunset over mountains"
term-llm image "logo design" --provider flux    # use specific provider
term-llm image "make it purple" -i photo.png    # edit existing image

Debugging

Use --debug to print provider-level diagnostics (requests, model info, etc.). Use --debug-raw for a timestamped, raw view of tool calls, tool results, and reconstructed requests. Raw debug is most useful for troubleshooting tool calling and search.

Debug Logging

term-llm maintains debug logs for troubleshooting. Use the debug-log command to view and manage them:

term-llm debug-log                           # Show recent logs
term-llm debug-log list                      # List available log files
term-llm debug-log show [file]               # Show a specific log file
term-llm debug-log tail                      # Show last N lines
term-llm debug-log tail --follow             # Follow logs in real-time
term-llm debug-log search "pattern"          # Search logs for a pattern
term-llm debug-log clean                     # Clean old log files
term-llm debug-log clean --days 7            # Keep only last 7 days
term-llm debug-log export --json             # Export logs as JSON
term-llm debug-log enable                    # Enable debug logging
term-llm debug-log disable                   # Disable debug logging
term-llm debug-log status                    # Show logging status
term-llm debug-log path                      # Print log directory path

Key flags:

Flag	Description
--days N	Limit to logs from last N days
--show-tools	Include tool calls/results in output
--raw	Show raw log entries without formatting
--json	Output as JSON
--follow	Follow logs in real-time (with tail)

Image Generation

Generate and edit images using AI models from Gemini, OpenAI, or Flux (Black Forest Labs).

term-llm image "a robot cat on a rainbow"

By default, images are:

• Saved to ~/Pictures/term-llm/ with timestamped filenames
• Displayed in terminal via icat (if available)
• Copied to clipboard (actual image data, pasteable in apps)

Image Flags

Flag	Short	Description
--input	-i	Input image to edit
--provider		Override provider (gemini, openai, flux)
--output	-o	Custom output path
--no-display		Skip terminal display
--no-clipboard		Skip clipboard copy
--no-save		Don't save to default location
--debug	-d	Show debug information

Image Examples

# Generate
term-llm image "cyberpunk cityscape at night"
term-llm image "minimalist logo" --provider flux
term-llm image "futuristic city" --provider xai  # uses Grok image model
term-llm image "watercolor painting" -o ./art.png

# Edit existing image (not supported by xAI)
term-llm image "add a hat" -i photo.png
term-llm image "make it look vintage" -i input.png --provider gemini
term-llm image "add sparkles" -i clipboard       # edit from clipboard

# Options
term-llm image "portrait" --no-clipboard        # don't copy to clipboard
term-llm image "landscape" --no-display         # don't show in terminal

Image Providers

Provider	Models	Environment Variable	Config Key
Gemini (default)	gemini-2.5-flash-image	GEMINI_API_KEY	image.gemini.api_key
OpenAI	gpt-image-1, gpt-image-1.5, gpt-image-1-mini	OPENAI_API_KEY	image.openai.api_key
xAI	grok-2-image-1212	XAI_API_KEY	image.xai.api_key
Flux	flux-2-pro, flux-2-max, flux-kontext-pro	BFL_API_KEY	image.flux.api_key
OpenRouter	various	OPENROUTER_API_KEY	image.openrouter.api_key

Image providers use their own credentials, separate from text providers. This allows using different API keys or accounts for text vs image generation.

Note: xAI image generation does not support image editing (-i flag).

File Editing

Edit files using natural language instructions:

term-llm edit "add error handling" --file main.go
term-llm edit "refactor to use interfaces" --file "*.go"
term-llm edit "fix the bug" --file utils.go:45-60     # only lines 45-60
term-llm edit "use the API" -f main.go -c api/client.go  # with context files

Edit Flags

Flag	Short	Description
--file	-f	File(s) to edit (required, supports globs)
--context	-c	Read-only reference file(s) (supports globs, 'clipboard')
--dry-run		Preview changes without applying
--provider		Override provider (e.g., openai:gpt-5.2-codex)
--per-edit		Prompt for each edit separately
--debug	-d	Show debug information

Context Files

Use --context/-c to include reference files that inform the edit but won't be modified:

term-llm edit "refactor to use the client" -f handler.go -c api/client.go -c types.go

Context files are shown to the AI as read-only references. This is useful when your edit depends on types, interfaces, or patterns defined elsewhere.

You can also pipe stdin as context, which is handy for git diffs:

git diff | term-llm edit "apply these changes" -f main.go
git show HEAD~1 | term-llm edit "undo this change" -f handler.go

Line Range Syntax

Both edit and ask support line range syntax to focus on specific parts of a file:

# Edit specific lines
term-llm edit "fix this" --file main.go:11-22    # lines 11 to 22
term-llm edit "fix this" --file main.go:11-      # line 11 to end
term-llm edit "fix this" --file main.go:-22      # start to line 22

# Ask about specific lines
term-llm ask -f main.go:50-100 "explain this function"

Diff Format

term-llm supports two edit strategies:

Format	Description	Best For
replace	Multiple parallel find/replace tool calls	Most models (default)
udiff	Single unified diff with elision support	Codex models, large refactors

The udiff format uses unified diff syntax with -... elision to efficiently replace large code blocks without listing every line:

--- file.go
+++ file.go
@@ func BigFunction @@
-func BigFunction() error {
-...
-}
+func BigFunction() error {
+    return newImpl()
+}

Configure in ~/.config/term-llm/config.yaml:

edit:
  diff_format: auto  # auto, udiff, or replace

• auto (default): Uses udiff for Codex models, replace for others
• udiff: Always use unified diff format
• replace: Always use multiple find/replace calls

Autonomous Loops

Run an agent in a loop until a completion condition is met. State persists in the filesystem—the agent reads/writes files to track progress, and each iteration starts with fresh context.

# Run until tests pass
term-llm loop --done "go test ./..." --tools all "fix the failing tests"

# Run until file contains marker
term-llm loop --done-file TODO.md:COMPLETE \
  "Implement features in {{TODO.md}}. Mark COMPLETE when done."

Loop Flags

Flag	Description
--done "cmd"	Exit when command returns 0
--done-file FILE:TEXT	Exit when file contains TEXT
--max N	Maximum iterations (0 = unlimited)
--history N	Inject last N iteration summaries to avoid repeating mistakes
--yolo	Auto-approve all tool operations (for unattended runs)

All standard flags work: --tools, --mcp, --agent, --provider, --search, etc.

File Expansion

Use {{file}} in your prompt to inline file contents. Files are re-read each iteration, so agents can update them for inter-iteration state:

term-llm loop --done "npm test" \
  "Implement the spec in {{SPEC.md}}. Track progress in {{TODO.md}}."

History

Use --history N to inject summaries of previous iterations. This helps the agent avoid repeating failed approaches:

term-llm loop --done "go test" --history 3 --tools all \
  "Fix the tests. Don't repeat failed approaches."

Each iteration summary includes tools used and a truncated output.

Examples

# Migration: run until no class components remain
term-llm loop --done "! grep -r 'React.Component' src/" --tools all \
  "Convert class components to hooks. One file at a time. Run tests after each."

# Research: run until conclusion written
term-llm loop --done-file RESEARCH.md:"## Conclusion" --tools read,write --search --max 20 \
  "Research WebGPU compute shaders. Current progress: {{RESEARCH.md}}. Write a Conclusion section when done."

# With an agent and iteration cap
term-llm loop @coder --done "make build" --max 20 --yolo \
  "Implement the feature described in {{SPEC.md}}"

MCP Servers

MCP (Model Context Protocol) lets you extend term-llm with external tools—browser automation, database access, API integrations, and more.

# Add from registry
term-llm mcp add playwright              # search and install
term-llm mcp add @anthropic/mcp-server-fetch

# Add from URL (HTTP transport)
term-llm mcp add https://developers.openai.com/mcp

# Use with any command
term-llm exec --mcp playwright "take a screenshot of google.com"
term-llm ask --mcp github "list my open PRs"
term-llm chat --mcp playwright,filesystem

MCP Commands

Command	Description
mcp add <name-or-url>	Add server from registry or URL
mcp list	List configured servers
mcp info <name>	Show server info and tools
mcp run <server> <tool> [args]	Run MCP tool(s) directly
mcp remove <name>	Remove a server
mcp browse [query]	Browse/search the MCP registry
mcp path	Print config file path

Adding Servers

From the registry (stdio transport):

term-llm mcp add playwright           # search by name
term-llm mcp add @playwright/mcp      # exact package
term-llm mcp browse                   # interactive browser

From a URL (HTTP transport):

term-llm mcp add https://developers.openai.com/mcp
term-llm mcp add https://mcp.example.com/api

Using MCP Tools

The --mcp flag works with all commands (ask, exec, edit, chat):

# Single server
term-llm ask --mcp fetch "summarize https://example.com"
term-llm exec --mcp playwright "take a screenshot of google.com"
term-llm edit --mcp github -f main.go "update based on latest API"

# Multiple servers (comma-separated)
term-llm chat --mcp playwright,filesystem,github

# In chat, toggle servers with Ctrl+M

Running Tools Directly

Use mcp run to call MCP tools without going through the LLM:

# Simple key=value arguments
term-llm mcp run filesystem read_file path=/tmp/test.txt

# JSON arguments for complex values
term-llm mcp run server tool '{"nested":{"deep":"value"}}'

# Multiple tools in one invocation
term-llm mcp run server tool1 key=val tool2 key=val

# Read file contents into a parameter with @path
term-llm mcp run server tool content=@/tmp/big-file.txt

# Read from stdin with @-
cat data.json | term-llm mcp run server tool input=@-

Configuration

MCP servers are stored in ~/.config/term-llm/mcp.json:

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "openai-docs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "authenticated-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Transport Types

Type	Config	Description
stdio	command + args	Runs as subprocess (npm/pypi packages)
http	url	Connects to remote HTTP endpoint

HTTP transport uses Streamable HTTP (MCP spec 2025-03-26).

Agents

Agents are named configuration bundles that define a persona with specific provider, model, system prompt, tools, and MCP servers. Use agents to switch between different workflows quickly.

Using Agents

Use the @agent prefix syntax or --agent flag:

term-llm ask @reviewer "review this code"     # use reviewer agent
term-llm chat @coder                          # start chat with coder agent
term-llm ask --agent reviewer "question"      # alternative syntax

Managing Agents

term-llm agents                              # List all agents
term-llm agents list                         # Same as above
term-llm agents list --builtin               # Only built-in agents
term-llm agents list --local                 # Only local agents
term-llm agents list --user                  # Only user agents
term-llm agents new my-agent                 # Create new agent
term-llm agents show reviewer                # Show agent configuration
term-llm agents edit reviewer                # Edit agent configuration
term-llm agents copy builtin/coder my-coder  # Copy agent to customize
term-llm agents path                         # Print agents directory

Agent Configuration

Agents are YAML files stored in ~/.config/term-llm/agents/:

# ~/.config/term-llm/agents/reviewer.yaml
name: Code Reviewer
description: Reviews code for best practices and potential issues

provider: anthropic
model: claude-sonnet-4-6

system_message: |
  You are a code reviewer. Focus on:
  - Code quality and best practices
  - Potential bugs and edge cases
  - Performance considerations
  - Security issues

tools:
  - read_file
  - grep
  - glob

mcp:
  - github

Agent search order: user agents → local agents → built-in agents

Skills

Skills are portable instruction bundles that provide specialized knowledge for specific tasks. Unlike agents, skills don't change the provider or model—they just add context.

Using Skills

term-llm ask --skills git "how to squash commits"   # use git skill
term-llm chat --skills git,docker                   # multiple skills
term-llm edit --skills refactoring -f main.go "refactor this"

Managing Skills

term-llm skills                              # List all skills
term-llm skills list                         # Same as above
term-llm skills list --local                 # Only local skills
term-llm skills list --user                  # Only user skills
term-llm skills new my-skill                 # Create new skill
term-llm skills show git                     # Show skill content
term-llm skills edit git                     # Edit skill
term-llm skills copy builtin/git my-git      # Copy skill to customize
term-llm skills browse                       # Browse available skills
term-llm skills validate my-skill            # Validate skill syntax
term-llm skills update                       # Update skills from sources
term-llm skills path                         # Print skills directory

Skill Configuration

Skills are YAML files stored in ~/.config/term-llm/skills/:

# ~/.config/term-llm/skills/git.yaml
name: Git Expert
description: Expertise in Git version control

instructions: |
  You are an expert in Git version control. When helping with Git:
  - Prefer rebase over merge for cleaner history
  - Use conventional commit messages
  - Explain the implications of destructive operations
  - Suggest .gitignore patterns when appropriate

Skill search order: user skills → local skills → built-in skills

Built-in Tools

term-llm includes built-in tools for file operations and shell access. Enable them with the --tools flag:

term-llm chat --tools read_file,shell,grep        # Enable specific tools
term-llm exec --tools read_file,write_file,edit_file,shell,grep,glob,view_image

Available Tools

Tool	Description
read_file	Read file contents (with line ranges)
write_file	Create/overwrite files
edit_file	Edit existing files
shell	Execute shell commands
grep	Search file contents (uses ripgrep)
glob	Find files by glob pattern
view_image	Display images in terminal (icat)
show_image	Show image file info
image_generate	Generate images via configured provider
ask_user	Prompt user for input
spawn_agent	Spawn child agents for parallel tasks
activate_skill	Activate a skill by name

Tool Permissions

Control which directories and commands tools can access:

# Allow read access to specific directories
term-llm chat --tools read,grep --read-dir /home/user/projects

# Allow write access to specific directories
term-llm chat --tools read,write,edit --read-dir . --write-dir ./src

# Allow specific shell commands (glob patterns)
term-llm chat --tools shell --shell-allow "git *" --shell-allow "npm test"

When a tool needs access outside approved directories, term-llm prompts for approval with options:

• Proceed once: Allow this specific action
• Proceed always: Allow for this session (memory only)
• Proceed always + save: Allow permanently (saved to config)

Shell Integration (Recommended)

Commands run by term-llm don't appear in your shell history. To fix this, add a shell function that uses --print-only mode.

Zsh

Add to ~/.zshrc:

tl() {
  local cmd=$(term-llm exec --print-only "$@")
  if [[ -n "$cmd" ]]; then
    print -s "$cmd"  # add to history
    eval "$cmd"
  fi
}

Bash

Add to ~/.bashrc:

tl() {
  local cmd=$(term-llm exec --print-only "$@")
  if [[ -n "$cmd" ]]; then
    history -s "$cmd"  # add to history
    eval "$cmd"
  fi
}

Then use tl instead of term-llm:

tl "find large files"
tl "install latest docker" -s      # with web search
tl "compress this folder" -a       # auto-pick best

Configuration

term-llm config        # Show current config
term-llm config edit   # Edit config file
term-llm config path   # Print config file path

Version & Updates

term-llm automatically checks for updates once per day and notifies you when a new version is available.

term-llm version       # Show version info
term-llm upgrade       # Upgrade to latest version
term-llm upgrade --version v0.2.0  # Install specific version

To disable update checks, set TERM_LLM_SKIP_UPDATE_CHECK=1.

Usage Tracking

View token usage and costs from local CLI tools:

term-llm usage                           # Show all usage
term-llm usage --provider claude-code    # Filter by provider
term-llm usage --provider term-llm       # term-llm usage only
term-llm usage --since 20250101          # From specific date
term-llm usage --breakdown               # Per-model breakdown
term-llm usage --json                    # JSON output

Supported sources: Claude Code, Gemini CLI, and term-llm's own usage logs.

Session Management

Chat sessions are automatically stored locally and can be managed with the sessions command. Each session is assigned a sequential number (#1, #2, #3...) for easy reference:

term-llm sessions                        # List recent sessions
term-llm sessions list --provider anthropic  # Filter by provider
term-llm sessions search "kubernetes"    # Search session content
term-llm sessions show 42                # Show session details (by number)
term-llm sessions show #42               # Same thing (explicit # prefix)
term-llm sessions export 42 [path.md]    # Export as markdown
term-llm sessions name 42 "my session"   # Set custom name
term-llm sessions delete 42              # Delete a session
term-llm sessions reset                  # Delete all sessions
term-llm chat --resume=42                # Resume a session by number

Sessions are stored in a SQLite database at ~/.local/share/term-llm/sessions.db. Configure session storage in your config:

sessions:
  enabled: true       # Master switch (default: true)
  max_age_days: 0     # Auto-delete sessions older than N days (0=never)
  max_count: 0        # Keep at most N sessions (0=unlimited)

Conversation Inspector

While in chat or ask mode, press Ctrl+O to open the conversation inspector. This shows the full conversation history including tool calls and results, with vim-style navigation:

Key	Action
j/k	Scroll up/down
g/G	Go to top/bottom
e	Toggle expand/collapse
q	Close inspector

Config is stored at ~/.config/term-llm/config.yaml:

default_provider: anthropic

providers:
  # Built-in providers - type is inferred from the key name
  anthropic:
    model: claude-sonnet-4-6

  openai:
    model: gpt-5.2
    credentials: codex  # or "api_key" (default)

  xai:
    model: grok-4-1-fast  # grok-4, grok-3, grok-code-fast-1

  openrouter:
    model: x-ai/grok-code-fast-1
    app_url: https://github.com/samsaffron/term-llm
    app_title: term-llm

  gemini:
    model: gemini-3-flash-preview  # uses GEMINI_API_KEY

  gemini-cli:
    model: gemini-3-flash-preview  # uses ~/.gemini/oauth_creds.json

  zen:
    model: glm-4.7-free
    # api_key is optional - leave empty for free tier

  copilot:
    model: gpt-4.1  # free tier, or gpt-5.2-codex for paid

  # Local LLM providers (require explicit type)
  # Run 'term-llm models --provider ollama' to list available models
  # ollama:
  #   type: openai_compatible
  #   base_url: http://localhost:11434/v1
  #   model: llama3.2:latest

  # Custom OpenAI-compatible endpoints
  # cerebras:
  #   type: openai_compatible
  #   base_url: https://api.cerebras.ai/v1  # /chat/completions appended automatically
  #   # url: https://api.cerebras.ai/v1/chat/completions  # alternative: full URL, used as-is
  #   model: llama-4-scout-17b
  #   api_key: ${CEREBRAS_API_KEY}
  #   models:  # optional: enable autocomplete for --provider cerebras:<TAB>
  #     - llama-4-scout-17b-16e-instruct
  #     - llama-4-maverick-17b-128e-instruct
  #     - qwen-3-32b

exec:
  suggestions: 3  # number of command suggestions
  # provider: openai    # override provider for exec only
  # model: gpt-4o       # override model for exec only
  instructions: |
    I use Arch Linux with zsh.
    I prefer ripgrep over grep, fd over find.

ask:
  # provider: anthropic
  # model: claude-opus-4  # use a smarter model for questions
  instructions: |
    Be concise. I'm an experienced developer.

edit:
  # provider: openai
  # model: gpt-5.2-codex  # Codex models are optimized for code edits
  diff_format: auto  # auto, udiff, or replace

image:
  provider: gemini  # gemini, openai, xai, flux, or openrouter
  output_dir: ~/Pictures/term-llm

  gemini:
    api_key: ${GEMINI_API_KEY}
    # model: gemini-2.5-flash-image

  openai:
    api_key: ${OPENAI_API_KEY}
    # model: gpt-image-1

  xai:
    api_key: ${XAI_API_KEY}
    # model: grok-2-image-1212

  flux:
    api_key: ${BFL_API_KEY}
    # model: flux-2-pro

  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    # model: google/gemini-2.5-flash-image

search:
  provider: duckduckgo  # exa, brave, google, or duckduckgo (default)

  # exa:
  #   api_key: ${EXA_API_KEY}

  # brave:
  #   api_key: ${BRAVE_API_KEY}

  # google:
  #   api_key: ${GOOGLE_SEARCH_API_KEY}
  #   cx: ${GOOGLE_SEARCH_CX}

tools:
  max_tool_output_chars: 20000  # truncate tool outputs before sending to LLM (default 20000, 0 to disable)

Per-Command Provider/Model

Each command (exec, ask, edit) can have its own provider and model, overriding the global default:

default_provider: anthropic  # global default

providers:
  anthropic:
    model: claude-sonnet-4-6
  openai:
    model: gpt-5.2
  zen:
    model: glm-4.7-free

exec:
  provider: zen       # exec uses Zen (free)
  model: glm-4.7-free

ask:
  model: claude-opus-4  # ask uses global provider with a smarter model

edit:
  provider: openai
  model: gpt-5.2       # edit uses OpenAI

Precedence (highest to lowest):

1. CLI flag: --provider openai:gpt-5.2
2. Per-command config: exec.provider / exec.model
3. Global config: default_provider + providers.<name>.model

Reasoning Effort (OpenAI)

For OpenAI models, you can control reasoning effort by appending -low, -medium, -high, or -xhigh to the model name:

term-llm ask --provider openai:gpt-5.2-xhigh "complex question"  # max reasoning
term-llm exec --provider openai:gpt-5.2-low "quick task"         # faster/cheaper

Or in config:

providers:
  openai:
    model: gpt-5.2-high  # effort parsed from suffix

Effort	Description
low	Faster, cheaper, less thorough
medium	Balanced (default if not specified)
high	More thorough reasoning
xhigh	Maximum reasoning (only on gpt-5.2)

Extended Thinking (Anthropic)

For Anthropic models, you can enable extended thinking by appending -thinking to the model name:

term-llm ask --provider anthropic:claude-sonnet-4-6-thinking "complex question"

Or in config:

providers:
  anthropic:
    model: claude-sonnet-4-6-thinking  # enables 10k token thinking budget

Extended thinking allows Claude to reason through complex problems before responding. The thinking process uses ~10,000 tokens and is not shown in the output.

Web Search

When using -s/--search, some providers (Anthropic, OpenAI, xAI, Gemini) have native web search built-in. xAI also includes X (Twitter) search. Others use external tools (configurable search provider + Jina Reader).

You can force external search even for providers with native support—useful for consistency, debugging, or when native search doesn't work well for your use case.

CLI flags:

term-llm ask "latest news" -s --no-native-search  # Force external search tools
term-llm ask "latest news" -s --native-search     # Force native (override config)

Global config (applies to all providers):

search:
  force_external: true  # Never use native search, always use external tools

Per-provider config:

providers:
  gemini:
    model: gemini-2.5-flash
    use_native_search: false  # Always use external search for this provider

  anthropic:
    model: claude-sonnet-4-6
    # use_native_search: true  # Default: use native if available

Priority (highest to lowest):

1. CLI flag: --native-search or --no-native-search
2. Global config: search.force_external: true
3. Provider config: use_native_search: false
4. Default: use native search if provider supports it

Search Providers

When using external search (non-native), you can choose from multiple search providers:

Provider	Environment Variable	Description
DuckDuckGo (default)	—	Free, no API key required
Exa	EXA_API_KEY	AI-native semantic search
Brave	BRAVE_API_KEY	Independent index, privacy-focused
Google	GOOGLE_SEARCH_API_KEY + GOOGLE_SEARCH_CX	Google Custom Search

Configure in ~/.config/term-llm/config.yaml:

search:
  provider: exa  # exa, brave, google, or duckduckgo (default)

  exa:
    api_key: ${EXA_API_KEY}

  brave:
    api_key: ${BRAVE_API_KEY}

  google:
    api_key: ${GOOGLE_SEARCH_API_KEY}
    cx: ${GOOGLE_SEARCH_CX}  # Custom Search Engine ID

Run term-llm config to see which search providers have credentials configured.

Credentials

Most providers use API keys via environment variables. Some providers use OAuth credentials from companion CLIs:

Provider	Credentials Source	Description
anthropic	ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, or OAuth	Anthropic API key or OAuth token
openai	OPENAI_API_KEY	OpenAI API key
chatgpt	~/.config/term-llm/chatgpt_creds.json	ChatGPT Plus/Pro OAuth
copilot	~/.config/term-llm/copilot_creds.json	GitHub Copilot OAuth
gemini	GEMINI_API_KEY	Google AI Studio API key
gemini-cli	~/.gemini/oauth_creds.json	gemini-cli OAuth (Google Code Assist)
xai	XAI_API_KEY	xAI API key
openrouter	OPENROUTER_API_KEY	OpenRouter API key
zen	ZEN_API_KEY (optional)	Empty for free tier

Anthropic, ChatGPT, Copilot, and Gemini CLI work without any API key if you have a subscription or the CLI installed and logged in:

term-llm ask --provider anthropic "question"  # uses OAuth token (runs `claude setup-token` on first use)
term-llm ask --provider chatgpt "question"    # uses ChatGPT Plus/Pro subscription
term-llm ask --provider copilot "question"    # uses GitHub Copilot OAuth
term-llm ask --provider gemini-cli "question" # uses ~/.gemini/oauth_creds.json

Dynamic Configuration

For advanced setups, term-llm supports dynamic resolution of API keys and URLs using special prefixes. These are resolved lazily—only when actually making an API call, not when loading config.

1Password Integration (op://)

Retrieve API keys from 1Password using secret references:

providers:
  my-provider:
    type: openai_compatible
    base_url: https://api.example.com/v1
    api_key: "op://Private/My API Key/credential"

For multiple 1Password accounts, use the ?account= query parameter:

providers:
  work-llm:
    type: openai_compatible
    base_url: https://llm.company.com/v1
    api_key: "op://Engineering/LLM Service/api_key?account=company.1password.com"

This requires the 1Password CLI (op) to be installed and signed in.

DNS SRV Records (srv://)

Discover server endpoints dynamically via DNS SRV records:

providers:
  internal-llm:
    type: openai_compatible
    url: "srv://_llm._tcp.internal.company.com/v1/chat/completions"
    api_key: ${LLM_API_KEY}

The SRV record is resolved to https://host:port/path. This is useful for:

• Load-balanced services with multiple backends
• Internal services with dynamic IPs
• Kubernetes services exposed via external-dns

Shell Commands ($())

Execute arbitrary shell commands to get values:

providers:
  vault-backed:
    type: openai_compatible
    base_url: https://api.example.com/v1
    api_key: "$(vault kv get -field=api_key secret/llm)"

  aws-secrets:
    type: openai_compatible
    base_url: https://api.example.com/v1
    api_key: "$(aws secretsmanager get-secret-value --secret-id llm-key --query SecretString --output text)"

Combined Example

Using SRV discovery with 1Password credentials:

providers:
  production-llm:
    type: openai_compatible
    model: "Qwen/Qwen3-30B-A3B"
    url: "srv://_vllm._tcp.ml.company.com/v1/chat/completions"
    api_key: "op://Infrastructure/vLLM Cluster/credential?account=company.1password.com"

When you run term-llm config, these show as [set via 1password] or [set via command] without actually resolving the values (no 1Password prompt until you make an API call).

Diagnostics

Enable diagnostic logging to capture detailed information when edits fail and retry. This is useful for debugging and tuning prompts:

diagnostics:
  enabled: true
  # dir: /custom/path  # optional, defaults to ~/.local/share/term-llm/diagnostics/

When an edit fails and retries, two files are written:

• edit-retry-{timestamp}.json - Structured data for programmatic analysis
• edit-retry-{timestamp}.md - Human-readable with syntax-highlighted code blocks

Each diagnostic captures:

• Provider and model used
• Full system and user prompts
• LLM's partial response before failure
• Failed search pattern or diff
• Current file content
• Error reason

Shell Completions

Generate and install shell completions:

term-llm config completion zsh --install   # Install for zsh
term-llm config completion bash --install  # Install for bash
term-llm config completion fish --install  # Install for fish

License

MIT