CLI 参考

这是每个 lean-ctx 命令的详尽参考。速查表请参阅 快速参考。分析和仪表盘详情请参阅 分析指南。

Shell 压缩

这些命令通过 lean-ctx 的 95 多个压缩模式运行 shell 命令。输出在到达 LLM 之前会自动去除噪声、模板和冗余内容。

lean-ctx -c "<command>"

执行任意 shell 命令并压缩其输出。别名：lean-ctx exec。

lean-ctx -c "git status"
lean-ctx -c "kubectl get pods -A"
lean-ctx -c "cargo build 2>&1"
lean-ctx exec "docker ps"

通过 lean-ctx init 安装的 shell 钩子会自动处理常见命令--您无需为它们添加前缀 -c。仅对 shell 钩子未覆盖的命令显式使用 -c。

lean-ctx shell

启动一个交互式 shell 会话，所有命令输出都会被压缩。包装您的默认 shell（zsh、bash 或 fish）。

lean-ctx shell
# Now every command output is compressed automatically
git log --oneline -20
docker compose logs
# Exit with Ctrl+D or 'exit'

原始模式

需要完整未修改输出时跳过压缩。三种激活方式：

# CLI flag
lean-ctx -c --raw git log --stat

# Shell function (after lean-ctx init --global)
lean-ctx-raw kubectl get pods -o yaml

# MCP parameter
ctx_shell(command="cat package.json", raw=true)

# Environment variable
LEAN_CTX_RAW=1 lean-ctx -c npm list

# Bypass command - guaranteed zero compression
lean-ctx bypass "git diff HEAD~1"

# Kill-switch: disable ALL compression
LEAN_CTX_DISABLED=1 lean-ctx -c git status

lean-ctx bypass "<command>"

以保证零压缩的方式运行任意命令。内部在执行命令前设置 LEAN_CTX_RAW=1。当你需要绝对确定输出未被修改时使用。

lean-ctx bypass "git diff HEAD~1"     # guaranteed unmodified output
lean-ctx bypass "docker logs myapp"   # no compression, no truncation
lean-ctx bypass "npm audit"           # raw vulnerability report

提示： bypass 等同于 LEAN_CTX_RAW=1 lean-ctx -c "command"，但更方便。命令字符串直接传递给 shell。

文件操作

通过 CLI 直接访问 lean-ctx 的文件读取、搜索和导航工具。这些与 MCP 服务器为 AI 工具提供的操作相同。

lean-ctx read <file> [-m <mode>]

以可选的压缩模式读取文件。默认模式为 full。

lean-ctx read src/main.rs                    # auto-selects best mode
lean-ctx read src/main.rs -m full            # full content (cached)
lean-ctx read src/main.rs -m map             # dependency graph + exports
lean-ctx read src/main.rs -m signatures      # tree-sitter AST extraction
lean-ctx read src/main.rs -m aggressive      # syntax-stripped
lean-ctx read src/main.rs -m entropy         # Shannon entropy filtered
lean-ctx read src/main.rs -m diff            # changed lines only
lean-ctx read src/main.rs -m task            # IB-filtered for current task
lean-ctx read src/main.rs -m reference       # cross-reference context
lean-ctx read src/main.rs -m lines:10-50     # specific line range
lean-ctx read src/main.rs -m lines:10-50,80  # multiple ranges

lean-ctx diff <file1> <file2>

两个文件之间的压缩 diff，附带结构化变更摘要。

lean-ctx diff old.rs new.rs

lean-ctx grep <pattern> [path]

压缩的分组搜索文件内容。内部使用 ripgrep。

lean-ctx grep "pub fn" src/
lean-ctx grep "TODO" .
lean-ctx grep "async fn.*Result" rust/src/

lean-ctx find <pattern> [path]

按名称模式查找文件。遵循 .gitignore 并输出紧凑的文件树。

lean-ctx find "*.rs" src/
lean-ctx find "test_*" .

lean-ctx ls [path]

以紧凑树形图显示目录列表，附带文件计数。

lean-ctx ls
lean-ctx ls src/components/

lean-ctx deps [path]

显示项目依赖图。检测包管理器并提取依赖项。

lean-ctx deps .
lean-ctx deps frontend/

读取模式

读取模式控制 lean-ctx read 和 MCP 工具 ctx_read 如何压缩文件内容。为您的使用场景选择合适的模式：

signatures 模式支持的语言：TypeScript、JavaScript、Rust、Python、Go、Java、C、C++、Ruby、C#、Kotlin、Swift、PHP（通过 tree-sitter 共 14 种）。

设置与配置

lean-ctx setup

一条命令完成设置。自动检测您的 shell（zsh/bash/fish/PowerShell），查找已安装的 AI 工具，配置 MCP 服务器和 shell 钩子。安装 lean-ctx 后运行一次。

lean-ctx setup

内部运行以下三个步骤：

1. 安装 shell 别名（init --global）
2. 为每个检测到的 AI 工具配置 MCP
3. 验证一切正常（doctor）

Since v3.3.3, the setup wizard includes a Premium Features step where you can configure Terse Agent Mode, Tool Result Archive, and Output Density interactively.

lean-ctx init [--global | <shell>]

将 shell 压缩别名安装到您的 shell 配置文件中。

# File-based: writes aliases directly into your shell profile
lean-ctx init           # install for current shell
lean-ctx init --global  # same, explicit flag

# Eval-based: prints hook code to stdout (like starship, zoxide, atuin)
eval "$(lean-ctx init bash)"        # bash: add to ~/.bashrc
eval "$(lean-ctx init zsh)"         # zsh: add to ~/.zshrc
lean-ctx init fish | source         # fish: add to config.fish
lean-ctx init powershell | Invoke-Expression  # PowerShell: add to $PROFILE

此操作会向 ~/.zshrc、~/.bashrc、~/.config/fish/config.fish 或您的 PowerShell 配置文件写入一段配置。该配置包含 git、docker、npm、cargo 等 95 多个命令的别名。

eval 模式： eval 方法将 hook 代码输出到 stdout，确保它始终与已安装的二进制版本匹配。这与 starship、zoxide 和 atuin 使用的模式相同。升级后 hook 永远不会过时。

lean-ctx init --agent <name>

无需完整 setup 即可为特定 AI 工具配置 MCP。

lean-ctx init --agent cursor
lean-ctx init --agent claude
lean-ctx init --agent codex
lean-ctx init --agent gemini
lean-ctx init --agent antigravity  # alias for gemini
lean-ctx init --agent windsurf
lean-ctx init --agent copilot
lean-ctx init --agent cline
lean-ctx init --agent roo
lean-ctx init --agent aider
lean-ctx init --agent continue
lean-ctx init --agent zed
lean-ctx init --agent void
lean-ctx init --agent amp
lean-ctx init --agent trae
lean-ctx init --agent kilo
lean-ctx init --agent opencode
lean-ctx init --agent pi           # installs pi-lean-ctx npm package
lean-ctx init --agent custom       # generic MCP config

lean-ctx config [set <key> <value>]

查看或编辑存储在 ~/.lean-ctx/config.toml 中的配置。

lean-ctx config                        # show current config
lean-ctx config set ultra_compact true # enable ultra-compact mode
lean-ctx config set tee_on_error true  # log errors to ~/.lean-ctx/tee/
lean-ctx config set checkpoint_interval 20

Settable Configuration Keys

lean-ctx config set theme neon
lean-ctx config set slow_command_threshold_ms 3000
lean-ctx config set passthrough_urls "localhost:3000,api.example.com"
lean-ctx config set rules_scope both

lean-ctx doctor

运行 8 项安装和环境诊断：

• 二进制文件已安装且在 PATH 中
• Shell 钩子已激活
• 已检测编辑器的 MCP 配置
• 统计文件持久性
• Cache 目录
• 检测到支持的 shell
• AI 工具检测
• 版本检查
• Rules injection status
• Claude Code instructions (rules + skill installed)
• Build integrity verification

lean-ctx doctor

lean-ctx update [--check]

从 GitHub Releases 自更新 lean-ctx 二进制文件。

lean-ctx update         # download and install latest version
lean-ctx update --check # check if a newer version is available (no install)

lean-ctx login <email> [--password <pw>] v3.3.3

Authenticate with LeanCTX Cloud. Only attempts login - does not create a new account. If password is omitted, prompts interactively.

lean-ctx login user@example.com
lean-ctx login user@example.com --password mypassword

On success, saves the API key to ~/.lean-ctx/cloud/credentials.json and syncs your data. If your email is not yet verified, you'll receive a reminder to check your inbox.

lean-ctx register <email> [--password <pw>] v3.3.3

Create a new LeanCTX Cloud account. Separate from login - no auto-fallback. A verification email is sent after registration.

lean-ctx register user@example.com
lean-ctx register user@example.com --password mypassword

lean-ctx forgot-password <email>

Request a password reset email for an existing LeanCTX Cloud account.

lean-ctx forgot-password user@example.com

lean-ctx uninstall

移除所有 lean-ctx 配置：shell 钩子、所有编辑器的 MCP 配置和 ~/.lean-ctx/ 数据目录。并打印删除二进制文件的说明。

lean-ctx uninstall

分析与仪表板

详细指南（含截图和解读），请参阅 分析指南。

lean-ctx gain [flags]

显示终身 token 节省量的可视化终端仪表板。

由 GainEngine 驱动--统一的可观测性 API，把压缩指标、成本跟踪与会话分析汇总为一个 GainScore（0–100）。使用内置 ModelPricing（无需网络）以及 13 类的 TaskClassifier。

修饰参数

lean-ctx gain                          # overview with GainScore
lean-ctx gain --score                  # GainScore breakdown
lean-ctx gain --cost --model=claude-4-sonnet  # cost for specific model
lean-ctx gain --tasks                  # task classification heatmap
lean-ctx gain --agents                 # multi-agent cost attribution
lean-ctx gain --deep                   # full deep-dive report
lean-ctx gain --wrapped --period=week  # weekly summary
lean-ctx gain --live                   # real-time monitoring
lean-ctx gain --graph                  # ASCII savings graph
lean-ctx gain --daily                  # daily breakdown
lean-ctx gain --pipeline               # per-stage compression breakdown
lean-ctx gain --json > stats.json      # machine-readable export

ctx_gain MCP 工具提供同样的可编程分析--AI 代理可在会话中直接查询 token 节省、成本拆分与 GainScore。参见 MCP 工具参考。

lean-ctx cep [--json]

CEP（Cognitive Efficiency Protocol）影响报告，显示分数趋势、cache 命中率和模式分布。

Internally uses ctx_gain --score to compute the Context Efficiency Protocol score. The CEP score ranges from 0–100 and measures how efficiently context is being utilized across read modes, shell compression, and deduplication.

lean-ctx cep               # show CEP score with breakdown
lean-ctx cep --json        # JSON output for CI/CD integration

lean-ctx dashboard [--port=N] [--project=<path>]

打开 http://localhost:3333 上的交互式 Web 仪表板。包含交互式图表、会话历史、活跃代理和项目知识面板。

lean-ctx dashboard                        # opens at localhost:3333
lean-ctx dashboard --port=8080            # custom port
lean-ctx dashboard --project=~/my-app     # scoped to a single project

lean-ctx wrapped [--week|--month|--all]

生成可分享的 token 节省 "Wrapped" 报告卡片。

lean-ctx wrapped
lean-ctx wrapped --month
lean-ctx wrapped --all

会话管理

lean-ctx sessions [list|show|cleanup]

管理存储在 ~/.lean-ctx/sessions/ 的 CCP（Context Continuity Protocol）会话。

lean-ctx sessions list
lean-ctx sessions show
lean-ctx sessions cleanup

lean-ctx session

显示采用率统计--您的工作流中有多少使用了 lean-ctx 压缩。

lean-ctx session

知识管理

对持久项目知识库的完整 CLI 访问。事实、模式和约定在会话间保留，实现累积式项目理解。

lean-ctx knowledge remember <value> --category <c> --key <k>

将事实存储到项目知识库中，可选附带置信度分数。

lean-ctx knowledge remember "Uses JWT for auth" --category auth --key token-type
lean-ctx knowledge remember "PostgreSQL 16" --category arch --key database --confidence 0.95

lean-ctx knowledge recall [query] [--category <c>] [--mode auto|semantic|hybrid]

通过查询文本或类别检索事实。启用嵌入时支持语义召回。

lean-ctx knowledge recall "authentication"
lean-ctx knowledge recall --category security
lean-ctx knowledge recall "auth" --mode semantic

lean-ctx knowledge search <query>

跨所有项目和会话搜索匹配的事实。

lean-ctx knowledge search "database migration"

lean-ctx knowledge export [--format json|jsonl|simple] [--output <path>]

导出项目知识库。默认输出到 stdout（支持管道）。三种格式：json（完整原生格式，默认）、jsonl（每行一条事实）、simple（社区兼容数组，用于从其他工具迁移）。

lean-ctx knowledge export                                  # full JSON to stdout
lean-ctx knowledge export --format jsonl --output backup.jsonl  # JSONL to file
lean-ctx knowledge export --format simple | jq '.[].key'   # pipe-friendly

lean-ctx knowledge import <path> [--merge replace|append|skip-existing] [--dry-run]

从 JSON、JSONL 或原生导出文件导入事实。自动检测输入格式。默认合并策略为 skip-existing（安全—从不覆盖）。

lean-ctx knowledge import backup.json --dry-run             # preview changes
lean-ctx knowledge import facts.jsonl --merge replace        # overwrite existing
lean-ctx knowledge import migration.json --merge skip-existing

lean-ctx knowledge remove --category <c> --key <k>

从知识库中移除特定事实。

lean-ctx knowledge remove --category auth --key token-type

lean-ctx knowledge status

显示知识库概览—事实数量、类别和最后更新时间。

lean-ctx knowledge status

lean-ctx knowledge health

健康报告，包含质量指标、过期事实检测和空间平衡。

lean-ctx knowledge health

基准测试

lean-ctx benchmark run [path] [--json]

使用 tiktoken (o200k_base) 对项目文件运行真实 token 基准测试。测量每种读取模式在每个文件上的精确节省量。

lean-ctx benchmark run                # benchmark current directory
lean-ctx benchmark run src/           # benchmark specific path
lean-ctx benchmark run . --json       # output as JSON

lean-ctx benchmark report [path]

从基准测试结果生成可分享的 Markdown 报告。

lean-ctx benchmark report             # generate report for current directory
lean-ctx benchmark report src/ > BENCHMARK.md

Tee 与过滤器

lean-ctx tee [list|clear|show <file>|last]

管理保存在 ~/.lean-ctx/tee/ 中的完整输出 tee 文件。使用 lean-ctx tee last 查看最近保存的输出。通过 tee_mode 配置：always、failures 或 never。

lean-ctx filter [list|validate|init]

管理 ~/.lean-ctx/filters/*.toml 中的自定义压缩过滤器。

# Create example filter
lean-ctx filter init

# List loaded filters
lean-ctx filter list

# Validate filter syntax
lean-ctx filter validate

实用工具

lean-ctx discover

扫描您的 shell 历史记录，查找可以从压缩中受益但未被拦截的命令。显示每命令 token 估算和美元节省预测。

lean-ctx discover

lean-ctx ghost [--json]

Reveals hidden token waste in your workflow - shows unoptimized shell commands, redundant reads, and oversized contexts with a monthly USD savings estimate. Use --json for CI integration.

lean-ctx ghost
lean-ctx ghost --json

lean-ctx cheatsheet

在终端中打印所有命令和工作流程的简洁速查表。

lean-ctx cheatsheet

lean-ctx tee [list|clear|show <file>]

管理存储在 ~/.lean-ctx/tee/ 中的错误日志文件。当配置中启用 tee_on_error 时，失败的命令会将完整输出记录在此。

lean-ctx tee list
lean-ctx tee show 2026-03-29_10-30.log
lean-ctx tee clear

lean-ctx slow-log [list|clear]

查看或清除 ~/.lean-ctx/slow-commands.log 中的慢命令日志。执行时间超过预期的命令会记录在此，用于调试。

lean-ctx slow-log list
lean-ctx slow-log clear

项目 Graph

构建或检查项目的 dependency graph。Graph 索引文件关系（imports、exports、符号），用于 heat-ranking、意图分析和智能预加载。

lean-ctx graph build

扫描项目目录并构建 dependency graph 索引。使用 MCP 工具时，graph 也会自动构建。

lean-ctx graph build

上下文 Heat Map

将文件的 token 密度和 dependency graph 连接度可视化为彩色 heat map。具有高 token 数量和大量连接的文件显示更热。

lean-ctx heatmap

在终端中显示当前项目所有文件的 heat map，按热度分数排序（token 数量与 graph 连接度的组合）。

lean-ctx heatmap

安全级别

LeanCTX 将每个受支持的命令归类到一个安全级别，该级别决定输出被压缩的激进程度。较高级别永远不会移除安全关键信息（错误、CVE、健康状态）。

lean-ctx safety-levels

显示详细表格，准确展示每种命令类型的压缩方式、保留的数据以及激活的全局安全功能。

lean-ctx safety-levels

全局安全功能适用于所有级别：安全针扫描（保留 CRITICAL、FATAL、panic、CVE-*、OOMKilled 等）、保障比率（阻止 >95% 的压缩）、身份验证检测（掩码令牌/密码）和最小令牌阈值（50 个令牌以下不压缩）。

Shell 别名

运行 lean-ctx init --global 后，以下别名可在您的 shell 中使用。无需重启即可开关压缩：

lean-ctx-status    # check current state
lean-ctx-off       # temporarily disable for human reading
git log            # now shows full, uncompressed output
lean-ctx-on        # re-enable for AI sessions

何时禁用：当您想亲自阅读命令输出（调试、查看日志）时关闭压缩。在启动 AI 编码会话前重新开启。

Server & Services

lean-ctx can run as a long-lived HTTP server, a TUI watcher, or a network proxy. These modes are useful for CI/CD pipelines, multi-agent orchestration, and headless environments.

lean-ctx serve [flags] feature: http-server

Start an HTTP/REST server that exposes all MCP tools as REST endpoints. Requires the http-server feature gate. Supports both stateful (session-persisted) and stateless modes.

# Start server with defaults
lean-ctx serve

# Public-facing with rate limits
lean-ctx serve --host=0.0.0.0 --port=8080 --rate-limit=50

# Stateless mode for CI/CD
lean-ctx serve --stateless --timeout=60000

# With CORS for web dashboard
lean-ctx serve --cors --port=9119

Once running, all MCP tools are available at POST /v1/tools/<tool_name>. A health endpoint is at GET /health.

lean-ctx watch

Start lean-ctx in TUI (Terminal UI) mode with a live event bus. Monitors all MCP activity in real time and writes events to ~/.lean-ctx/events.jsonl for post-hoc analysis.

lean-ctx watch                          # full TUI with live event stream
lean-ctx watch --filter=ctx_shell       # only shell events
lean-ctx watch --no-tui                 # headless JSONL to stdout

lean-ctx proxy <start|stop|status> feature-gated

Manage the lean-ctx network proxy. When active, the proxy intercepts MCP traffic and applies compression transparently. Requires the proxy feature gate.

lean-ctx proxy start       # start proxy daemon
lean-ctx proxy status      # check if proxy is running
lean-ctx proxy stop        # stop the proxy

Terse Agent

The Terse Agent controls output density for AI agent communication. It persists across sessions and can be toggled at any time. See also the Configuration guide.

lean-ctx terse [lite|full|ultra|off]

Query or set the Terse Agent mode. Without arguments, shows the current mode. With an argument, sets the mode persistently.

lean-ctx terse              # show current terse mode
lean-ctx terse lite         # set to lite mode
lean-ctx terse full         # set to full mode
lean-ctx terse ultra        # maximum compression
lean-ctx terse off          # disable terse agent

Token Reports

Generate detailed token usage reports for analysis and cost tracking.

lean-ctx token-report [flags]

Display a comprehensive token usage report for the current or specified project. Also available as lean-ctx report-tokens (alias).

lean-ctx token-report                          # current session summary
lean-ctx token-report --period=week            # weekly report
lean-ctx token-report --by-tool --period=month # monthly per-tool breakdown
lean-ctx report-tokens --json > report.json    # alias, JSON export

Cache Management

Manage the lean-ctx content cache that accelerates repeated reads and avoids redundant compression.

lean-ctx cache <subcommand> [flags]

lean-ctx cache status                          # cache stats
lean-ctx cache clear                           # purge entire cache
lean-ctx cache invalidate "src/**/*.rs"        # invalidate Rust files
lean-ctx cache reset --project=~/my-app        # reset for one project

Gotchas

Manage known gotchas - common pitfalls, edge cases, and warnings that lean-ctx tracks across your projects. Also available as lean-ctx bugs (alias).

lean-ctx gotchas [list|add|remove|clear]

lean-ctx gotchas list
lean-ctx gotchas add "ctx_shell timeout on M1 with Docker Rosetta"
lean-ctx gotchas remove 3
lean-ctx bugs list            # alias for gotchas list
lean-ctx bugs clear

Buddy

The Buddy (also called Pet) is an interactive companion feature that provides contextual tips, encouragement, and session insights. Purely cosmetic and opt-in.

lean-ctx buddy [status|on|off|name <name>]

lean-ctx buddy status          # check buddy state
lean-ctx buddy on              # enable buddy
lean-ctx buddy name Ferris     # name your buddy
lean-ctx pet off               # alias - disable buddy

Context Packages

创建、管理和共享可移植的上下文包...

lean-ctx pack create --name <name> [--layers <layers>]

Create a context package from the current project. Layers default to all available (knowledge,graph,session,patterns,gotchas).

lean-ctx pack create --name my-pkg
lean-ctx pack create --name api-knowledge --layers knowledge,gotchas
lean-ctx pack create --name full-snapshot --version 2.0.0

lean-ctx pack list

List all installed packages with version and auto-load status.

lean-ctx pack list

lean-ctx pack info <name>

Show detailed metadata, layers, stats, and integrity hash for a package.

lean-ctx pack info my-pkg

lean-ctx pack export <name> [-o <file>]

Export a package to a portable .lctxpkg file. Default output is <name>.lctxpkg.

lean-ctx pack export my-pkg
lean-ctx pack export my-pkg -o shared/my-pkg.lctxpkg

lean-ctx pack import <file>

Import a package from a .lctxpkg file. Verifies SHA-256 integrity before installing.

lean-ctx pack import my-pkg.lctxpkg

lean-ctx pack install <name>

Merge a package's context into the current project — knowledge facts, graph nodes, and gotchas.

lean-ctx pack install my-pkg

lean-ctx pack remove <name>

Remove a package from the local registry.

lean-ctx pack remove my-pkg

lean-ctx pack auto-load <name> <on|off>

Enable or disable auto-loading. When enabled, the package is merged into the project context automatically when ctx_overview runs at session start.

lean-ctx pack auto-load my-pkg on
lean-ctx pack auto-load my-pkg off

Instructions

Manually retrieve MCP server instructions. Useful in headless or non-interactive environments where the MCP handshake does not automatically deliver instructions.

lean-ctx instructions [flags] v3.3.x

lean-ctx instructions                   # print formatted instructions
lean-ctx instructions --raw             # raw text for piping
lean-ctx instructions --json            # JSON with metadata
lean-ctx instructions --inject          # inject into running session

This is particularly useful when integrating lean-ctx into CI/CD pipelines or custom agent frameworks that don't support the MCP instructions handshake natively.