Reference

CLI reference.

Command help captured from LeanCTX 3.10.2, with the installed runtime as the final reference.

Status by featureReviewed September 2026

Start with the everyday commands

lean-ctx --version
lean-ctx status
lean-ctx doctor
lean-ctx read README.md -m full --fresh
lean-ctx dashboard
lean-ctx gain

For an end-to-end setup, use the quickstart. For MCP JSON inputs, use the tool reference; MCP names are not terminal commands.

Find a command by task

This directory maps every top-level branch and alias in the reviewed CLI dispatcher to its purpose and guide. Its classifications belong to the recorded source snapshot. Local is an implementation scope; Advanced needs the exact installed contract. Historical Research, Removed and Internal entries do not define the current Engine's product scope. See Engine architecture for that scope.

Set up & connect

lean-ctx initLocal: Install a shell integration or configure a named host.Guide
lean-ctx setupLocal: Choose integrations and options in guided setup.Guide
lean-ctx onboardLocal: Apply the zero-question onboarding path; changes local host configuration.Guide
lean-ctx installLocal: Setup alias; --repair refreshes supported integrations.Guide
lean-ctx bootstrapLocal: Run non-interactive setup and repair.Guide
lean-ctx wrapLocal: Connect a supported host, preserving its prior configuration.Guide
lean-ctx unwrapLocal: Restore the configuration saved by the corresponding wrapper.Guide
lean-ctx statusLocal: Inspect setup and connection status.Guide
lean-ctx doctorLocal: Diagnose integrations; --fix explicitly applies repairs.Guide
lean-ctx cheatLocal: Print the context-tool cheat sheet.Aliases: cheatsheet, cheat-sheetGuide
lean-ctx --versionLocal: Print the installed version.Alias: -VGuide
lean-ctx helpLocal: Show concise help or help all.Guide
lean-ctx --helpLocal: Print command help.Alias: -hGuide

Read & run commands

lean-ctx -cLocal: Execute a command and shape its output.Alias: execGuide
lean-ctx -tLocal: Track a command while preserving its full output.Alias: --trackGuide
lean-ctx shellLocal: Open an interactive shell with compression integration.Alias: --shellGuide
lean-ctx readLocal: Read a file at the requested level of detail.Guide
lean-ctx callAdvanced: Invoke a named tool through the CLI bridge.Guide
lean-ctx diffLocal: Compare file content.Guide
lean-ctx grepLocal: Search source text with bounded output.Guide
lean-ctx globLocal: Find paths matching a file pattern.Guide
lean-ctx findLocal: Find files with compressed output.Guide
lean-ctx lsLocal: List a directory.Guide
lean-ctx filterLocal: Manage custom shell-output compression filters; not read-time security policies.Guide
lean-ctx teeLocal: Inspect or clear retained command-output files.Guide
lean-ctx terseLocal: Set the output-density preference; compression is its alias.Alias: compressionGuide
lean-ctx rawLocal: Run with uncompressed output; other command effects still apply.Alias: bypassGuide

Index & inspect code

lean-ctx healthLocal: Report code-health signals and navigability.Guide
lean-ctx embeddingsRemoved: Provisioning is unavailable in the reviewed implementation despite older help.Guide
lean-ctx modelAdvanced: Inspect or explicitly install/remove a managed local model.Guide
lean-ctx enable-gpuPlatform-specific: Install the CUDA-enabled binary for supported x86_64 GNU/Linux systems.Alias: gpuGuide
lean-ctx indexLocal: Inspect, build or watch lexical, graph and semantic indexes.Guide
lean-ctx semantic-searchLocal: Search the configured semantic index.Alias: search-codeGuide
lean-ctx exploreLocal: Explore code iteratively with available source citations.Guide
lean-ctx repomapLocal: Generate a structural repository map.Alias: repo-mapGuide
lean-ctx depsLocal: Inspect project dependencies.Guide
lean-ctx graphLocal: Build or query dependencies, symbols and impact relationships.Guide
lean-ctx smellsLocal: Run supported static code-smell rules.Guide
lean-ctx overviewLocal: Summarize project structure, optionally for a task.Guide

Plan & control context

lean-ctx triageAdvanced: Inspect agreement in local semantic-shadow decisions.Guide
lean-ctx cognitiveAdvanced: Inspect local cognitive/context-state diagnostics.Guide
lean-ctx ledgerLocal: Inspect retained context pressure; prune, push or evict entries.Guide
lean-ctx controlLocal: Set include, exclude, pin and priority preferences.Alias: context-controlGuide
lean-ctx planLocal: Prepare a task-oriented context plan under a budget.Alias: context-planGuide
lean-ctx compileLocal: Compile selected context under configured limits.Alias: context-compileGuide
lean-ctx kitResearch: Inspect/load local TOML or context-package substrate; first-class Kit semantics remain Research.Alias: kitsGuide
lean-ctx compressLocal: Create a compression checkpoint or compare original and emitted text.Guide
lean-ctx compactAdvanced: Invoke local transcript/context compaction.Guide
lean-ctx profileLocal: Manage named context-configuration presets.Guide
lean-ctx toolsLocal: Choose MCP visibility profiles or inspect local tool health.Guide

Remember & recover

lean-ctx packLocal: Prepare a context package, including PR context.Guide
lean-ctx snapshotLocal: Create, inspect, verify or restore recorded context snapshots.Guide
lean-ctx verify-cacheLocal: Inspect session-cache behavior for repeated reads.Alias: cache-selftestGuide
lean-ctx sessionLocal: Record and resume the current session context.Guide
lean-ctx importLocal: Import supported AI-session history; review content before retention.Guide
lean-ctx checkpointsAdvanced: List provenance checkpoints for the workspace.Guide
lean-ctx knowledgeLocal: Store, recall, search, export or import project facts.Guide
lean-ctx skillifyAdvanced: Distill recurring patterns into local rule files.Guide
lean-ctx summaryLocal: Record and recall AI session summaries.Guide
lean-ctx sessionsLocal: Manage saved session records; distinct from the singular session command.Alias: session-storeGuide
lean-ctx cacheLocal: Inspect or clear read-cache state.Guide
lean-ctx gotchasLocal: Inspect and manage retained error patterns.Alias: bugsGuide
lean-ctx learnResearch: Local learning entry point; not autonomous optimization.Guide

Integrate applications & sources

lean-ctx addonResearch: Marketplace/addon surface is unavailable as a public product.Alias: addonsGuide
lean-ctx pluginRemoved: Removed subprocess-plugin commands; do not use the old help as an install recipe.Alias: pluginsGuide
lean-ctx providerLocal: Configure or inspect source-provider operations.Guide
lean-ctx serveLocal: Serve MCP over HTTP or the configured local daemon transport.Guide
lean-ctx proxyLocal: Manage the optional model-request proxy.Guide
lean-ctx engineAdvanced: Versioned local context-view, source-recovery and Agent Tools transport.Guide
lean-ctx oclaAdvanced: Low-level context lifecycle protocol surface.Guide
lean-ctx mcpLocal: Enter the stdio MCP server path; also the no-argument behavior.Guide

Inspect activity & usage

lean-ctx badgeLocal: Render a usage badge.Guide
lean-ctx gainLocal: Inspect observed/estimated local context usage; not a workload benchmark.Guide
lean-ctx spendLocal: Inspect provider usage captured by supported integrations.Guide
lean-ctx finopsAdvanced: Inspect local usage/cost reporting.Guide
lean-ctx roiLocal: Inspect local modeled ROI; not a guarantee about a provider bill.Guide
lean-ctx output-savingsLocal: Estimate local output-token changes; quality needs a separate evaluation.Alias: output_savingsGuide
lean-ctx token-reportLocal: Report project, session and context-processing token/memory signals.Alias: report-tokensGuide
lean-ctx visualizeLocal: Write an interactive HTML report.Guide
lean-ctx cepLocal: Inspect context-processing metrics, modes and cache trends.Guide
lean-ctx dashboardLocal: Open the local Context Cockpit, editor tab or HTML export.Guide
lean-ctx discoverLocal: Find opportunities to shape commands in local shell history.Guide
lean-ctx ghostLocal: Inspect hidden input/output waste estimates.Guide
lean-ctx heatmapLocal: Inspect file-level context usage signals.Guide
lean-ctx wrappedLocal: Generate a shareable local usage summary.Guide
lean-ctx statsLocal: Inspect runtime statistics.Guide
lean-ctx introspectAdvanced: Inspect detailed local runtime state.Guide
lean-ctx buddyLocal: Show the optional data-driven terminal companion.Alias: petGuide

Evaluate & preserve evidence

lean-ctx savingsLocal: Inspect the local representation-change ledger and its verification artifacts.Guide
lean-ctx conformanceAdvanced: Run local conformance/self-test checks.Alias: selftestGuide
lean-ctx quality-labAdvanced: Inspect compression-quality diagnostics.Alias: quality_labGuide
lean-ctx value-reportLocal: Summarize recorded task outcomes and cost.Alias: value_reportGuide
lean-ctx evidence-exportAdvanced: Export local evidence artifacts.Guide
lean-ctx evidenceAdvanced: Inspect/export evidence bundles; provider comparison generation is not yet available.Guide
lean-ctx shadowAdvanced: Inspect local shadow-mode comparisons.Guide
lean-ctx scenarioAdvanced: Run a configured scenario; review its execution and data scope.Guide
lean-ctx measureAdvanced: Record baseline/treatment periods and compare local observations.Guide
lean-ctx proofAdvanced: Work with proof artifacts; not a compliance certification.Guide
lean-ctx proveAdvanced: Generate local decision-loop evidence.Guide
lean-ctx verifyAdvanced: Verify supported reports or evidence bundles according to their contract.Guide
lean-ctx evalAdvanced: Scaffold/run with-versus-without evaluation and verify artifacts.Guide
lean-ctx auditAdvanced: Inspect local audit, evidence or determinism reports.Guide
lean-ctx benchmarkAdvanced: Local representation or task evaluation; inspect the chosen subcommand.Guide
lean-ctx benchmark-runAdvanced: Advanced benchmark-runner path; result scope depends on the declared workload.Alias: bench-runGuide
lean-ctx calibrateAdvanced: Evaluate calibration and require evidence before applying eligible changes.Guide
lean-ctx pairAdvanced: Paired-run evaluation utilities; not a public pairing service.Guide

Apply rules & boundaries

lean-ctx policyMixed: Inspect and validate local packs; organization policy controls remain Research.Guide
lean-ctx rulesLocal: Inspect, synchronize or lint local rule files.Guide
lean-ctx instructionsAdvanced: Inspect or manage local instruction context.Guide
lean-ctx allowLocal: Add a command to the shell allowlist.Guide
lean-ctx securityLocal: Inspect posture or configure supported secret-defense controls.Guide
lean-ctx yoloSensitive: Disable path/command containment; secret redaction is a separate setting.Guide
lean-ctx secureLocal: Restore secure defaults.Alias: lockdownGuide
lean-ctx trustLocal: Explicitly trust a project boundary.Guide
lean-ctx untrustLocal: Revoke a project trust entry.Guide
lean-ctx hardenSensitive: Apply supported hardening operations.Guide
lean-ctx export-rulesAdvanced: Export rules for supported hosts.Guide
lean-ctx safety-levelsLocal: Inspect the safety-level model.Alias: safetyGuide

Configure & maintain

lean-ctx daemonLocal: Manage the local IPC daemon and supported login autostart.Guide
lean-ctx configLocal: Inspect, validate or change configuration.Guide
lean-ctx themeLocal: List, select, import or export terminal themes.Guide
lean-ctx slow-logLocal: Inspect or clear the slow-command log.Guide
lean-ctx debug-logLocal: Inspect or clear opt-in tool/hook diagnostics.Guide
lean-ctx updateLocal: Check/install a release for the native update path.Alias: --self-updateGuide
lean-ctx restartLocal: Restart local runtime processes to apply configuration.Guide
lean-ctx stopSensitive: Stop all LeanCTX processes, including the daemon and proxy.Guide
lean-ctx dev-installMaintainer: Build, atomically install and restart a development checkout.Guide
lean-ctx codesign-setupPlatform-specific: Configure a stable signing identity on macOS.Guide
lean-ctx completionsLocal: Generate shell completion support.Guide
lean-ctx report-issueLocal: Prepare diagnostics for an issue report; review private details before sharing.Alias: reportGuide
lean-ctx uninstallSensitive: Remove runtime/integrations/data according to flags; preview with --dry-run.Guide
lean-ctx telemetryLocal: Inspect or change the telemetry preference.Guide

Historical service and research commands

lean-ctx learningResearch: Inspect/import/export local adaptive-learning state.Guide
lean-ctx billingResearch: Development billing/account surface; not a public purchase path.Guide
lean-ctx complianceResearch: Research compliance artifact; not compliance certification.Guide
lean-ctx agentResearch: Local agent-bus compatibility; not a public orchestration service.Guide
lean-ctx teamResearch: Hosted team/gateway experiment, not a supported team product.Guide
lean-ctx enterpriseResearch: Organizational integration experiments; scope is not a shipped service.Guide
lean-ctx loginResearch: Hosted account evaluation, not required for local context use.Guide
lean-ctx registerResearch: Hosted account registration experiment.Guide
lean-ctx forgot-passwordResearch: Hosted account recovery experiment.Guide
lean-ctx syncResearch: Hosted/index synchronization experiment.Guide
lean-ctx contributeResearch: Development data-contribution experiment.Guide
lean-ctx cloudResearch: Hosted status/synchronization experiments.Guide
lean-ctx upgradeResearch: Hosted upgrade entry point; not an available self-serve purchase.Guide

Compatibility & integration internals

lean-ctx demoInternal: Internal demonstration entry point; not product evidence.Guide
lean-ctx watchRemoved: Removed terminal dashboard. Use dashboard, cep, or index watch instead.Guide
lean-ctx editor-signalInternal: Host-generated editor signal; not a user setup command.Guide
lean-ctx editor-sessionInternal: Host-generated session marker.Guide
lean-ctx __completeInternal: Shell completion protocol; invoke through generated completion support.Guide
lean-ctx hookInternal: Host hook protocol; configured by setup and wrapper integration.Guide

When help and implementation differ

The source inventory was reviewed on 18 September 2026 at 5198ea1867. The captured help below comes from runtime 3.10.2 and is retained verbatim. Its plugin and embeddings-provisioning entries are stale: the inspected handlers and the installed commands report those paths removed or unavailable. The old watch terminal UI is also removed. Use the dashboard, indexing guide and extension boundaries for the supported next step.

Browse the captured help

The blocks below reproduce lean-ctx help all. Some commands are administrative, experimental or retained for compatibility. Read their status language and inspect command-specific help before running a mutation.

This help was captured on macOS. Its platform-specific examples are historical snapshot content, not the installation recipe for every system. Use the platform guide for Windows, macOS and Linux paths, shell syntax and service differences, and consult your installed command's help.

Runtime information

lean-ctx 3.10.2 — Context SDK for AI Agents

78 MCP tools | local context selection, shaping, reuse, recovery, and measurement

Getting started

    lean-ctx wrap <agent>          One-command setup (wrap cursor / wrap claude / wrap codex)
    lean-ctx unwrap <agent>        Undo wrap, restore pre-wrap config
    lean-ctx onboard               Connect all AI tools at once (zero questions)
    lean-ctx setup                 Guided setup with full control over every option
    lean-ctx doctor                Check that everything is wired up correctly
    lean-ctx gain                  Inspect local context-usage estimates (not a benchmark)
    (everything below is reference — run `lean-ctx help` for the short version)

Usage

    lean-ctx                       Start MCP server (stdio)
    lean-ctx serve                 Start MCP server (Streamable HTTP)
    lean-ctx serve --daemon        Start as background daemon (Unix Domain Socket)
    lean-ctx serve --stop          Stop running daemon
    lean-ctx serve --status        Show daemon status
    lean-ctx -t "command"          Track command (full output + stats, no compression)
    lean-ctx -c "command"          Execute with compressed output (used by AI hooks)
    lean-ctx -c --raw "command"    Execute without compression (full output)
    lean-ctx raw "command"         Raw escape hatch: full, exact output (alias: bypass)
    lean-ctx exec "command"        Same as -c
    lean-ctx shell                 Interactive shell with compression

Commands

    gain                           Local context-usage report (observed or estimated; not a benchmark)
    gain --live                    Live mode: auto-refreshes every 1s in-place
    gain --deep                    Full breakdown (cost + tasks + agents + heatmap combined)
    gain --graph                   30-day local context-usage chart
    gain --daily                   Bordered day-by-day table with USD
    gain --score                   Gain score breakdown (4 sub-scores + trend)
    gain --cost                    Agent cost attribution report (estimated)
    spend                          Measured provider bill (real model + billed tokens)
    spend --json                   Machine-readable measured spend
    output-savings [--json]        Local output-token estimate; evaluation claims require a declared quality gate
    value-report [--format F]      Task value report (table, markdown, or json)
    gain --tasks                   Task breakdown by category
    gain --agents                  Top agents by tool spend
    gain --by-tool [--json]        Per-tool local context breakdown (calls, tokens, USD, %)
    gain --heatmap                 Top files by observed token reduction
    gain --json                    Raw JSON export of all stats
    gain --pipeline                Pipeline compression stats
    gain --opportunity             Find missed savings in shell history (replaces discover/ghost)
    gain --raw [--json]            Plain stats output (machine-friendly)
    gain --reset                   Clear all token savings data
    gain --model=<model>           Model for USD pricing calculations
    gain --period=<week|month|all> Period for wrapped/stats (default: all)
    gain --limit=<N>               Row limit for tables (default: 10, max: 50)
    gain --wrapped                 Shareable Wrapped card (terminal)
    gain --svg [=<path>]           Shareable Wrapped card as SVG (social/OG image)
    gain --share [=<path>]         Self-hostable Wrapped page (HTML; alias: --page)
    gain --copy                    Copy a ready-to-post share line to the clipboard
    gain --svg|--share --open      Also open the written card/page in your browser
    gain --publish [--name=<n>]    Development-only local export (hosted publication is Research)
    gain --publish --leaderboard   Unavailable: public rankings are Research
    gain --link [CODE]             Development-only local pairing experiment
    gain --unpublish[=<id|url|all>]  Take a published card down (works even when publishing is off)
    config set gain.auto_publish true  Development-only local export setting (off by default)
    savings [--period day|week|month|all] [--format table|json|markdown] Local representation-change report; not comparable proof
    learning [status|export|import]  Local adaptive-learning state: inspect, export, import
         token-report [--json]          Token + memory report (project + session + CEP)
    pack --pr                      PR Context Pack (changed files, impact, tests, artifacts)
    snapshot create|list|show|verify|restore|publish|import  Context Time Machine: git-anchored, signed snapshots; replay, resume + share
    index <status|build|build-full|watch> [--force]  Codebase index utilities
    embeddings <status|provision>  Local ONNX Runtime for semantic embeddings (official CPU build, sha256-pinned)
    cep                            CEP report (compression metrics, cache, modes, trends)
    verify-cache [path] [--json]   Inspect local session-cache re-read behavior
    prove [--format table|json|markdown] [--output FILE]  Generate Decision Loop evidence report
    health [path] [--json] [--gate]  Code-health report: cognitive complexity, naming, navigability score + token tax
    dashboard [--port=N] [--host=H] [--base-path=/prefix] [--open=browser|none|vscode]  Open web dashboard (default: http://localhost:3333)
    serve [--host H] [--port N]    MCP over HTTP (Streamable HTTP, local-first)
    proxy start [--port=4444] [--detach]  API proxy: compress tool_results before LLM API
    proxy status                   Show proxy statistics
    daemon start|stop|restart|status  IPC daemon management
    daemon enable|disable          Auto-start daemon on login (systemd/LaunchAgent; prints service file)
    cache [list|clear|stats]       Show/manage file read cache
    sessions [list|show|delete|cleanup]  Manage saved session snapshots — PLURAL; see 'session' for live memory (alias: session-store)
    benchmark run [path] [--json]  Run a local representation comparison on project files
    benchmark report [path]        Generate a local Markdown report
    benchmark compare [--output F] Research-only comparative report; not a public benchmark claim
    benchmark scorecard [--json]   Local representation scorecard; not a matched-workload result
    cheatsheet                     Context-tool cheat sheet & quick reference
    onboard                        Zero-prompt golden path: connect tools + sensible defaults
    setup                          Guided setup: shell + editor + verify (full control)
    install                        Alias for setup; install --repair = non-interactive refresh
    bootstrap                      Non-interactive setup + fix (zero-config)
    status [--json]                Show setup + MCP + rules status
    init [--global]                Install shell aliases (zsh/bash/fish/PowerShell)
    init --agent <name>            Configure MCP for specific editor/agent
    read <file> [-m mode]          Read file with compression
    engine context-view ...        Versioned local Engine context transport
    engine recover ...             Exact source recovery for a prior Engine view
    engine tool-session ...        Persistent SDK Agent Tools transport
    diff <file1> <file2>           Compressed file diff
    grep <pattern> [path]          Search with compressed output
    find <pattern> [path]          Find files with compressed output
    ls [path]                      Directory listing with compression
    deps [path]                    Show project dependencies
    discover                       Find uncompressed commands in shell history
    discover --card [=<path>]      Shareable 'before lean-ctx' SVG from your history
    ghost [--json]                 Ghost Token report: find hidden token waste
    filter [list|validate|init]    Manage custom compression filters (~/.lean-ctx/filters/)
    session                        Live session memory — SINGULAR; see 'sessions' to manage snapshots
    session task <desc>            Set current task
    session finding <summary>      Record a finding
    session save                   Save current session
    session load [id]              Load session (latest if no ID)
    knowledge remember <value> --category <c> --key <k>   Store a fact
    knowledge recall [query] [--category <c>]             Retrieve facts
    knowledge search <query>       Cross-project knowledge search
    knowledge export [--format json|jsonl|simple] [--output <path>]  Export knowledge
    knowledge import <path> [--merge replace|append|skip-existing]   Import knowledge
    knowledge remove --category <c> --key <k>             Remove a fact
    knowledge status               Knowledge base summary
    overview [task]                Project overview (task-contextualized if given)
    explore <query> [--citation] [--depth=N]  Iterative code exploration → file:line citations
    compress [--signatures]        Context compression checkpoint
    compress diff <file|-> [--shell "cmd"] [--json]  Preview compression: original vs emitted + token diff
    config                         Show/edit configuration (~/.lean-ctx/config.toml)
    security [status]              Show security posture (containment + secret defense)
    yolo                           Disable containment: any path + any command (keeps secret redaction on)
    secure                         Restore secure defaults (path jail + shell gating + secret redaction)
    security secrets <on|off>      Toggle secret/.env redaction (separate from containment)
    allow <cmd>                    Allow one shell command (additive; granular re-enable after yolo)
    tools [minimal|standard|power|show|list]  How many MCP tools your agent sees
    profile [list|show|diff|create|set|suggest]  Manage local context configuration profiles
    kit [list|load|show|unload] [name]  Manage available local TOML/.ctxpkg substrate; first-class Kit semantics are Research
    theme [list|set|export|import] Customize terminal colors and themes
    tee [list|clear|show <file>|last] Manage output tee files (~/.lean-ctx/tee/)
    compression [off|lite|standard|max]  Set local output-density preference (alias: terse)
    slow-log [list|clear]          Show/clear slow command log (~/.lean-ctx/slow-commands.log)
    debug-log [list|tail N|clear|path]  Opt-in tool-call + hook-routing log (set debug_log / LEAN_CTX_DEBUG_LOG)
    update [<version>] [--check]   Update lean-ctx, or pin a version, from GitHub Releases
    enable-gpu [--check]           Install CUDA-enabled binary (x86_64 GNU/Linux)
    stop                           Stop ALL lean-ctx processes (daemon, proxy, orphans)
    restart                        Restart daemon (applies config.toml changes)
    dev-install                    Build release + atomic install + restart (for development)
    codesign-setup                 macOS: one-time stable signing identity (stops repeating TCC prompt, #356)
    gotchas [list|clear|export|stats] Bug Memory: view/manage auto-detected error patterns
    buddy [show|stats|ascii|json]  Token Guardian: your data-driven coding companion
    doctor integrations [--json]   Integration health checks (Cursor/Claude Code/CodeBuddy)
    doctor [--fix] [--json]        Run diagnostics (and optionally repair)
    doctor --migrate-check         v1.0 migration readiness audit (config, deprecations, data)
    smells [scan|summary|rules|file] [--rule=<r>] [--path=<p>] [--json]
                                   Code smell detection (Property Graph, 8 rules)
    control <action> [--target=<t>] Context field manipulation (exclude/pin/priority)
    plan <task> [--budget=N]       Context planning (optimal Phi-scored context plan)
    compile [--mode=<m>] [--budget=N] Context compilation (knapsack + Boltzmann)
    visualize [--output F] [--open] Generate interactive HTML report (D3.js graph)
    plugin list|enable|disable|info|init|hooks
                                   Manage lean-ctx plugins
    addon list|search|info|add|remove
                                   Unavailable: marketplace/addon surface is Research
    rules sync|diff|lint|status|init
                                   Local rules management; no public cross-agent governance product
    policy list|show|validate|coverage|org  Local policy-pack utilities; organization controls are Research
    compliance report|verify       Research-only compliance artifact; not a public CISO product claim
    uninstall [--keep-config] [--keep-binary] [--dry-run]
                                   Full clean removal: stops all processes, removes hooks,
                                   MCP configs, rules, autostart, data, AND the binary itself.
                                   --keep-config preserves MCP/rules · --keep-binary keeps the
                                   binary · --dry-run previews without changing anything

SHELL HOOK PATTERNS (95+):
    git       status, log, diff, add, commit, push, pull, fetch, clone,
              branch, checkout, switch, merge, stash, tag, reset, remote
    docker    build, ps, images, logs, compose, exec, network
    npm/pnpm  install, test, run, list, outdated, audit
    cargo     build, test, check, clippy
    gh        pr list/view/create, issue list/view, run list/view
    kubectl   get pods/services/deployments, logs, describe, apply
    python    pip install/list/outdated, ruff check/format, poetry, uv
    linters   eslint, biome, prettier, golangci-lint
    builds    tsc, next build, vite build
    ruby      rubocop, bundle install/update, rake test, rails test
    tests     jest, vitest, pytest, go test, playwright, rspec, minitest
    iac       terraform, make, maven, gradle, dotnet, flutter, dart
    data-eng  dbt, spark, alembic, flyway
    ai        ollama, mlflow
    security  semgrep, trivy, grype, syft, cosign, swiftlint
    vcs/tool  jj, mise, buf, gem, uv add/lock/tool
    edge/iac  pulumi, linkerd, argocd, vercel, fly, wrangler, skaffold, supabase
    utils     curl, grep/rg, find, ls, wget, env
    data      JSON schema extraction, log deduplication

Read modes

    auto                           Auto-select optimal mode (default)
    full                           Full content (cached re-reads = 13 tokens)
    map                            Dependency graph + API signatures
    signatures                     tree-sitter AST extraction (27 languages)
    task                           Task-relevant filtering (requires ctx_session task)
    reference                      One-line reference stub (cheap cache key)
    aggressive                     Syntax-stripped content
    entropy                        Shannon entropy filtered
    diff                           Changed lines only
    lines:N-M                      Specific line ranges (e.g. lines:10-50,80)

Environment

    LEAN_CTX_DISABLED=1            Bypass ALL compression + prevent shell hook from loading
    LEAN_CTX_ENABLED=0             Prevent shell hook auto-start (lean-ctx-on still works)
    LEAN_CTX_RAW=1                 Same as --raw for current command
    LEAN_CTX_AUTONOMY=false        Disable autonomous features
    LEAN_CTX_COMPRESS=1            Force compression (even for excluded commands)

Options

    --version, -V                  Show version
    --help, -h                     Show this help

Examples

    lean-ctx -c "git status"       Compressed git output
    lean-ctx -c "kubectl get pods" Compressed k8s output
    lean-ctx -c "gh pr list"       Compressed GitHub CLI output
    lean-ctx gain                  Visual terminal dashboard
    lean-ctx gain --live           Live auto-updating terminal dashboard
    lean-ctx gain --graph          30-day local context-usage chart
    lean-ctx gain --daily          Day-by-day breakdown with USD
         lean-ctx token-report --json   Machine-readable token + memory report
    lean-ctx dashboard             Open web dashboard at localhost:3333
    lean-ctx dashboard --host=0.0.0.0  Bind to all interfaces (remote access)
    lean-ctx gain --wrapped        Wrapped report card (recommended)
    lean-ctx gain --wrapped --period=month  Monthly Wrapped report card
    lean-ctx gain --svg            Shareable SVG card -> lean-ctx-wrapped.svg
    lean-ctx gain --svg=card.svg --period=month  Monthly SVG card to a chosen path
    lean-ctx gain --share          Self-hostable Wrapped page -> lean-ctx-wrapped.html
    lean-ctx gain --share --base-url=https://you.dev/w  Page with social preview meta
    lean-ctx gain --copy           Copy your share line to the clipboard
    lean-ctx gain --publish        Development-only local export (hosted publication is Research)
    lean-ctx savings               Local representation-change ledger; not comparable proof by itself
    lean-ctx savings verify        Re-check the savings ledger SHA-256 hash chain
    lean-ctx savings sign          Export an Ed25519-signed savings batch (ROI/audit artifact)
    lean-ctx savings verify-batch <file>  Verify a signed batch offline (no ledger needed)
    lean-ctx sessions list         List all CCP sessions
    lean-ctx sessions show         Show latest session state
    lean-ctx sessions delete <id>  Delete one saved session
    lean-ctx discover              Find local opportunities to shape shell output
    lean-ctx discover --card       Shareable 'before' SVG -> lean-ctx-before.svg
    lean-ctx onboard               One-command setup (shell + editors + verify)
    lean-ctx install --repair      Non-interactive repair path (merge-based)
    lean-ctx bootstrap             Non-interactive setup + fix (zero-config)
    lean-ctx bootstrap --json      Machine-readable bootstrap report
    lean-ctx init --global         Install shell aliases (includes lean-ctx-on/off/mode/status)
    lean-ctx-on                    Enable shell aliases in track mode (full output + stats)
    lean-ctx-off                   Disable all shell aliases
    lean-ctx-mode track            Track mode: full output, stats recorded (default)
    LEAN_CTX_DEBUG=1 lean-ctx-on   Show shell hook mode-change notices
    lean-ctx-mode compress         Compress mode: all output compressed (power users)
    lean-ctx-mode off              Same as lean-ctx-off
    lean-ctx-status                Show whether compression is active
    lean-ctx init --agent pi       Install Pi Coding Agent extension
  lean-ctx init --agent grok        Configure Grok (xAI) MCP + hooks
    lean-ctx doctor                Check PATH, config, MCP, and dashboard port
    lean-ctx doctor integrations   Detailed integration checks (Cursor/Claude Code/CodeBuddy)
    lean-ctx doctor --fix --json   Repair + machine-readable report
    lean-ctx status --json         Machine-readable current status
    lean-ctx session task "implement auth"
    lean-ctx session finding "auth.rs:42 — missing validation"
    lean-ctx knowledge remember "Uses JWT" --category auth --key token-type
    lean-ctx knowledge recall "authentication"
    lean-ctx knowledge search "database migration"
    lean-ctx overview "refactor auth module"
    lean-ctx compress --signatures
    lean-ctx read src/main.rs -m map
    lean-ctx grep "pub fn" src/
    lean-ctx deps .

GRAPH (project analysis):
    lean-ctx graph build [path]    Build/rebuild project graph index
    lean-ctx graph status          Show graph index statistics
    lean-ctx graph related <file>  List files related to a given file
    lean-ctx graph impact <file>   Show files impacted by changes to a file
    lean-ctx graph symbol <spec>   Inspect a symbol (format: <file>::<symbol>, or bare <symbol>)
    lean-ctx graph context <query> Query the property graph for a concept

HOSTED RESEARCH (unavailable unless LEAN_CTX_EXPERIMENTAL_HOSTED=1):
    cloud status                   Development-only hosted status check
    cloud upgrade                  Unavailable: hosted plans are not a public product path
    login <email>                  Development-only account evaluation
    register <email>               Development-only account evaluation
    forgot-password <email>        Development-only account evaluation
    sync                           Development-only hosted sync evaluation
    sync index <push|pull|status>  Development-only hosted-index evaluation
    cloud autosync <on|off|status> Development-only background-sync evaluation
    contribute                     Development-only data-contribution evaluation

Troubleshooting

    Commands broken?     lean-ctx-off             (fixes current session)
    Permanent fix?       lean-ctx uninstall       (removes all hooks)
    Manual fix?          Edit ~/.zshrc, remove the "lean-ctx shell hook" block
    Binary missing?      Aliases auto-fallback to original commands (safe)
    Preview init?        lean-ctx init --global --dry-run

WEBSITE: https://leanctx.com
GITHUB:  https://github.com/yvgude/lean-ctx

Check the version you are running

lean-ctx help
lean-ctx help all

Generated help can enumerate implementation surfaces that are not stable product contracts. Feature status explains that distinction. Setup, reset, cleanup, update and uninstall commands can change local state.

Sources & versions3 references Reviewed 18 Sept 2026

mod.rsrust/src/cli/dispatch/mod.rsReviewed checkout
help.rsrust/src/cli/dispatch/help.rsReviewed checkout
appendix-cli-map.mddocs/reference/appendix-cli-map.mdReviewed checkout

Core checkout: 5198ea1867
Installed runtime: 3.10.2
SDK release: 1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility