LLMTune CLI

AI CLI Agent for your terminal, powered by llmtune.io.

Full reference: CLI_GUIDE.md — or run llmtune guide --open
If Cursor says Unable to resolve resource, open llmtune-platform/docs/CLI_GUIDE.md instead (same content).

Quick Start

# Install globally
npm install -g @llmtune/cli

# Or run directly
npx @llmtune/cli

# Configure your API key
llmtune login

# Start coding
cd my-project
llmtune chat

Commands

| Command | Description | |---------|-------------| | llmtune login | Configure API key and settings | | llmtune chat | Start interactive coding session | | llmtune chat -p "explain this" | One-shot mode: send prompt and exit | | llmtune chat --attach src/foo.ts | Pre-load files into context | | llmtune chat --dry-run | Preview tool calls without executing | | llmtune chat --resume | Resume the latest auto-saved session | | llmtune chat --sandbox <mode> | Sandbox bash: off, available, or required | | llmtune models | List available models | | llmtune config | Show configuration | | llmtune config set <key> <value> | Update defaultModel, apiBase, or apiKey | | llmtune config unset <key> | Remove a config key | | llmtune doctor | Run setup diagnostics | | llmtune diagnostics | Inspect locally-recorded tool failures (list, path, clear, --json) | | llmtune guide | Path to full CLI reference (--open to launch) | | llmtune logout | Remove saved API key | | llmtune update | Check for CLI updates | | llmtune balance | Show account balance | | llmtune logs | List or clean local session logs | | llmtune skills list | List marketplace skills | | llmtune skills info <name> | Show skill details | | llmtune skills install <name> | Install a skill from marketplace | | llmtune skills publish <dir> | Publish a skill directory | | llmtune skills sign <dir> | Cryptographically sign a skill | | llmtune init | Scaffold .llmtuneignore and LLMTUNE.md | | llmtune chat -p "..." --json | One-shot with NDJSON events on stdout | | llmtune chat --mcp | Load MCP tools from mcp.json | | llmtune mcp | List MCP servers and tools |

Chat Commands

Inside the REPL, use these slash commands:

| Command | Description | |---------|-------------| | /help | Show available commands | | /exit | Exit the REPL | | /clear | Clear conversation history | | /context | Show token usage breakdown by category | | /compact | Summarize old messages to free tokens | | /uncompact | Restore original conversation from history | | /model <name> | Switch to a different model | | /stream | Toggle streaming mode | | /verbose | Toggle verbose tool output | | /trust <tool> | Skip confirmation for a tool | | /skills | List loaded skills | | /<skill> [args] | Execute a skill | | /memory | Show cross-session memory | | /memory clear | Clear all memory | | /save | Save session to file | | /install <skill> | Install a skill from marketplace | | /plan <message> | Preview tool plan (no execution) | | /sandbox [mode] | Docker sandbox for bash (off / available / required) | | /stats | Show session statistics | | /diff | Show diff of last file change | | /sessions | List saved conversation sessions | | /cost | Show session cost breakdown | | /undo | Undo last file change | | /balance | Show account balance | | /project | Show detected project info | | /branch [idx] | Fork conversation from an earlier message | | /theme <name> | Switch terminal color theme | | /route | Configure per-tool model routing | | /watch <glob> | Auto-refresh context on file changes | | /refresh | Force-clear context cache | | /failures | Summary of locally-recorded tool failures | | /usage | Account usage summary |

Interactive TUI tips

• Pick model/agent/skill/prompt — with the input empty, press ← (model), → (agent), ↓ (skill), ↑ (prompt). In any picker, just start typing to search (e.g. glm5 jumps to GLM 5.1); Tab cycles category, Enter selects, Esc closes.
• Stop a running turn — press Ctrl+C to interrupt the agent mid-task (the footer shows Ctrl+C to stop).
• Live tool output — bash output streams into the running tool row as it executes.

Skills

Skills are reusable workflows defined in SKILL.md files. They live in:

• ~/.llmtune/skills/<skill-name>/SKILL.md — user skills
• .llmtune/skills/<skill-name>/SKILL.md — project skills

Creating a Skill

Create a directory with a SKILL.md file:

my-skill/
  SKILL.md

Example SKILL.md:

---
description: "Explain code with clear diagrams"
user-invocable: true
allowed-tools: [read, glob, grep]
arguments: [file_path]
trust: local
---

Analyze the code in {{file_path}} and explain it with:
1. A high-level overview
2. Key functions and their purposes
3. Data flow diagram (in mermaid syntax)
4. Potential improvements

Trust Levels

| Level | Tools Allowed | Description | |-------|---------------|-------------| | local | All | Created by user, full trust | | community | read, glob, grep | Installed from marketplace, sandboxed | | verified | All | Reviewed by LLMTune team | | signed | All | Cryptographically signed by author |

Context System

The CLI automatically builds context from your workspace:

• Git context — current branch, recent commits, modified files
• Workspace snapshot — file types, key files, directory structure
• Project instructions — loaded from LLMTUNE.md or CLAUDE.md
• Memory — cross-session preferences and decisions stored in ~/.llmtune/memory/

Context is cached by git SHA — repeated requests are served from cache until you make a new commit.

.llmtuneignore

Create a .llmtuneignore file in your project root to exclude files from context (uses same patterns as .gitignore).

Smart Compaction

When conversations get long, /compact summarizes older messages using an LLM, preserving:

• User intent and requests
• Key technical decisions
• Files examined or modified
• Errors and resolutions

The original conversation is always preserved. Use /uncompact to restore it.

Docker Sandbox (Enterprise)

For enterprise environments, the CLI can run tools inside a Docker container:

llmtune chat --sandbox available   # use Docker when available
llmtune chat --sandbox required    # require Docker (enterprise)

Or toggle at runtime with /sandbox. Bash runs inside a Docker container when sandbox mode is enabled.

Memory

The CLI stores cross-session knowledge in ~/.llmtune/memory/:

• preferences.md — coding style, language preferences
• project-notes.md — architecture decisions
• decisions.md — key decisions made during sessions
• architecture.md — project structure notes

The agent reads these automatically and can write to them.

Telemetry

Session telemetry is stored locally in ~/.llmtune/logs/{session-id}.jsonl:

• Tool calls with latency
• LLM token usage and cost estimates
• Compaction events
• Errors with context

No data is sent externally unless you opt in:

llmtune telemetry status   # show opt-in state
llmtune telemetry on       # upload anonymized summaries after REPL sessions
llmtune telemetry off
llmtune telemetry export   # print summary JSON for latest session

Uploads include duration, tool counts, and model name only — never message content.

Subagents (REPL)

Run a bounded read-only child loop and inject the summary into your session:

/task explore find where auth is configured
/task review check error handling in src/api

Modes: explore (read, glob, grep) and review (+ web_fetch).

Skill signing keys

llmtune skills sign uses persistent RSA keys in ~/.llmtune/keys/. Regenerate with:

llmtune skills keygen

Windows

• bash prefers Git Bash when installed — so Unix commands (ls, grep, $VAR, &&, forward-slash paths) work natively. Override the path with LLMTUNE_BASH_PATH.
• Without Git Bash it falls back to cmd.exe with automatic Unix→Windows translation (and the agent gets actionable hints to retry with the right syntax).
• llmtune doctor checks PowerShell, paths, Git, and Docker.
• Prefer llmtune chat -p "..." from PowerShell for one-shot scripts.

MCP (experimental)

Configure MCP servers in .llmtune/mcp.json or ~/.llmtune/mcp.json:

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  ]
}

Run llmtune mcp to list tools, or llmtune chat --mcp to register them in the agent.

Configuration

Configuration is stored in ~/.llmtune/config.json:

{
  "apiKey": "sk_...",
  "apiBase": "https://api.llmtune.io/api/agent/v1",
  "defaultModel": "z-ai/GLM-5.1"
}

Directory Structure

~/.llmtune/
  config.json           # API key and settings
  trust.json            # Globally trusted tools (/trust)
  theme.json            # Terminal theme name
  skills/               # Installed skills
  memory/               # Cross-session memory
  sessions/             # Saved conversation history
  logs/                 # Telemetry JSONL files
  cache/                # Context cache (SHA-keyed)
  mcp.json              # MCP server definitions (optional)

What's New

v0.5.3

• Type-to-search in the model/agent/skill/prompt picker — type glm5 to jump to GLM 5.1.
• Git Bash on Windows — Unix commands run natively when Git Bash is installed.
• Live tool output — bash stdout/stderr streams into the running tool row.
• Local failure diagnostics — llmtune diagnostics / /failures from a ~/.llmtune/diagnostics log.
• Ctrl+C interrupts a running turn; render/async error guards keep the session alive.
• Cleaner streaming — one clean single-line preview while streaming; the formatted answer renders once.

See the full history — including all earlier releases — in CHANGELOG.md.

TUI branding (custom logo)

The interactive TUI (llmtune chat) animates a terminal-friendly logo in the header, footer, and while tools run. Frames are generated from your brand mark:

1. Place or replace cli/assets/logo.svg (SVG or PNG also works if you update the script).
2. Run npm run generate:logo (requires dev dependency sharp).
3. Rebuild: npm run build.

Committed output lives in src/tui/generated/logo-frames.ts so installs work without running the generator. Set LLMTUNE_STEP_NUMBERS=1 to prefix tool lines with Step N ·. Set LLMTUNE_COLLAPSE_TOOLS=1 to collapse tool rows into one summary after each assistant reply.

On llmtune chat startup, a welcome screen (honeycomb art + version) appears before the session; press Enter to continue. Skip with LLMTUNE_SKIP_SPLASH=1.

License

MIT