Operate your local runtime.

Check before changing

lean-ctx --version
lean-ctx status --json
lean-ctx doctor --json
lean-ctx config path
lean-ctx config validate

These checks establish the executable, host connection and effective configuration. A running daemon alone does not prove that your AI host is connected to it. Keep platform paths and service differences in mind, especially across Windows and WSL.

Choose the right process

Process	Purpose	Start or inspect
MCP over stdio	A host launches LeanCTX and exchanges tool calls over its standard streams	Configure through lean-ctx wrap or lean-ctx setup; the host owns the connection.
MCP over HTTP	An explicitly configured HTTP integration	lean-ctx serve; see HTTP API for transport and authentication.
Local IPC daemon	Shared local runtime used by supported integrations	lean-ctx daemon status; use lean-ctx daemon start when needed.
Dashboard	Browser interface for local inspection	lean-ctx dashboard; see the dashboard guide.
Request proxy	Optional processing and telemetry on a configured model-request path	lean-ctx proxy status; see request proxy before enabling it.

On supported macOS/Linux installations, lean-ctx daemon enable installs login autostart and lean-ctx daemon disable stops/removes that service. LaunchAgent and systemd user services differ. Windows support for the CLI does not imply an equivalent native login-service implementation.

lean-ctx restart applies a runtime restart. lean-ctx stop stops all LeanCTX processes, including the proxy and daemon; it is not the command to close one dashboard tab. Restarting or stopping interrupts active integrations. Close a foreground dashboard with Ctrl+C in its own terminal.

Separate tool profiles from context profiles

Control	What changes	Inspection
Tool profile	How many MCP tools the host is offered; visibility is still affected by policy and host support	lean-ctx tools show, lean-ctx tools list
Context profile	A named context-configuration preset	lean-ctx profile list, lean-ctx profile show, lean-ctx profile diff <a> <b>
Configuration	Runtime settings, directories, limits and enabled capabilities	lean-ctx config path, lean-ctx config show, lean-ctx config validate

Choose a tool profile with lean-ctx tools minimal, lean-ctx tools standard or lean-ctx tools power. lean-ctx tools health reports local context-budget and stale-content signals; it is not a profile name. Reconnect the host if it does not refresh the tool list automatically.

lean-ctx profile create <name> --from <base> creates a context preset. lean-ctx profile set <name> prints Bash/zsh activation guidance (export LEAN_CTX_PROFILE=...). In PowerShell, set the same variable with $env:LEAN_CTX_PROFILE = "<name>", replacing <name> with an existing profile. It does not retroactively reconfigure every running AI process. See the configuration reference before editing values.

Inspect output and logs

lean-ctx tee list
lean-ctx tee last
lean-ctx slow-log list
lean-ctx debug-log path

• Tee output retains command output where that path is enabled. lean-ctx tee show <file> opens a retained file; MCP archives use their returned archive identifier instead.
• Slow log helps identify expensive commands. It is not an end-to-end model-latency benchmark.
• Debug log is opt-in through debug_log or LEAN_CTX_DEBUG_LOG. lean-ctx debug-log tail 50 inspects recent entries. Logs may contain project and command details: review them before sharing.
• Cache is separate from knowledge. lean-ctx cache stats and lean-ctx cache list inspect read-cache state; clearing it is not the same as deleting session history or durable facts.

Use troubleshooting to isolate a failure before enabling more logging or changing global settings.

Maintain retained data deliberately

lean-ctx session manages live session memory; lean-ctx sessions manages saved session snapshots. Start with lean-ctx sessions list and lean-ctx knowledge status.

Cleanup, delete, reset and clear actions mutate local records. Export needed knowledge before removing it, and distinguish caches, saved sessions, snapshots and durable knowledge. Their storage and recovery contracts differ; see memory and snapshots.

Update or remove the installation

Use the installation method that owns your executable. Follow the platform update recipes for Homebrew, npm or downloaded archives. lean-ctx update --check checks the native updater; lean-ctx update <version> can select a release for installations managed through that path.

After updating, check the version and host connection again. An SDK companion Engine has its own version requirement; do not replace it solely because a newer CLI exists.

To remove an installation, preview the effects first:

lean-ctx uninstall --dry-run

The uninstall path can stop processes and remove hooks, host configuration, local data and the binary. --keep-config and --keep-binary preserve different parts; inspect the installed help before executing it. To undo only one host integration, prefer its lean-ctx unwrap <agent> path.

lean-ctx dev-install builds, atomically installs and restarts a development checkout. It is a maintainer operation, not the normal user update path. codesign-setup concerns macOS signing only.

Personalize the terminal

lean-ctx theme list lists terminal themes; lean-ctx theme set <name> changes one. This does not change model behavior or permissions. Shell completion and the optional local companion live under lean-ctx completions and lean-ctx buddy; they are separate from context processing.

Sources & versions6 references · Reviewed 18 Sept 2026

• mod.rsrust/src/cli/dispatch/network/mod.rsReviewed checkout
• lifecycle.rsrust/src/cli/dispatch/lifecycle.rsReviewed checkout
• profile_cmd.rsrust/src/cli/profile_cmd.rsReviewed checkout
• config_cmd.rsrust/src/cli/config_cmd.rsReviewed checkout
• debug_log_cmd.rsrust/src/cli/debug_log_cmd.rsReviewed checkout
• mod.rsrust/src/uninstall/mod.rsReviewed 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