lithe-cli

lithe-cli is the command-line interface for lithe — the storage-free ReAct agent kernel. Installing it pulls in lithe automatically and gives you a lithe command: chat with an agent that reads and writes files in your workspace, runs code, searches the web through MCP tools, inspects stored runs, and undoes a run's mutations.

pip install lithe-cli

Configure

There is no default endpoint — the CLI refuses to run rather than silently hitting some third-party URL. The easiest way in is the wizard: on the first lithe chat / lithe run (or any time, via lithe config) an interactive terminal prompts for the three essentials and saves them to $LITHE_HOME/config.json (mode 0600 — it holds the key). An optional connectivity probe catches typos before your first turn.

To configure by hand instead, point the CLI at any OpenAI-compatible endpoint:

export LITHE_API_KEY=sk-...
export LITHE_BASE_URL=https://your-endpoint/api/v1
export LITHE_MODEL=your-model

Resolution order is flag (--api-key, --base-url, --model) > environment > saved config file, per key. The wizard never runs without a TTY on both ends, so pipes and CI keep the hard refusal; --no-setup restores that fail-fast behavior on terminals too. lithe config --show peeks at the saved values with a masked key.

LITHE_HOME (default ~/.lithe) locates the run store; the agent's workspace defaults to the current directory (--workspace to change).

lithe doctor prints the effective configuration — endpoint (with a masked key), config file, store, workspace, sandbox backend, skills, MCP servers — so you can see what a run would use before starting one.

Use

One-shot task

$ cd my-project
$ lithe run "总结 README.md 的要点，存到 SUMMARY.md"
  ⚒ read_file {"path": "README.md"}
  ✓ 已读取 README.md（120 行） 0.1s
  ⚒ write_file {"path": "SUMMARY.md", "content": "..."}
  ✓ 写入 SUMMARY.md 0.0s
已把要点写入 SUMMARY.md。
── done · steps 3 · tokens 2100 · cost 0.0042

--stream streams tokens as they generate; -v adds per-call usage/context gauges; --max-steps caps the tool loop; --context-window enables fullness gauges.

Interactive chat

$ lithe chat
╭──────────────────────────────────────╮
│ lithe 0.4.0                          │
│ model   your-model                   │
│ workdir /home/me/my-project          │
│ /help 查看会话命令，/exit 退出       │
╰──────────────────────────────────────╯
lithe ❯ 把 a.txt 改成三行待办清单
  ⚒ write_file {"path": "a.txt", ...}
  ✓ 写入 a.txt 0.0s
已完成。
── done · steps 2 · tokens 180
lithe ❯ /exit

History carries across turns within a session (each turn is its own run in the store, replayed as context for the next). /new clears the session, /tools lists the registered tools, /help lists the commands.

Extra capabilities

The kernel ships these as bundles; the CLI grants them per flag:

$ lithe run --code "用 run_code 验证 results.csv 的行数"
$ lithe run --shell "检查当前目录的项目状态"
$ lithe chat --skills ~/my-skills --mcp @~/mcp.json

Undo a run

The bundled file and todo tools register reverters, so undo works with zero configuration:

$ lithe runs                     # find the run
run           status  steps  cost  task
────────────  ──────  ─────  ────  ────────────────
abc123def456  done    3      0.01  总结 README.md …
$ lithe undo abc123def456
✓ 已撤销 2 个操作（run abc123def456）

A file the run created is deleted; a file it overwrote is restored. (run_code side effects are not revertible — its tool description warns the model.)

Inspect

$ lithe runs                     # stored runs (newest last)
$ lithe log abc123def456         # messages + actions of one run
$ lithe doctor                   # config + capability status

Tools

$ lithe tools                    # what the agent can do
tool          category  description
────────────  ────────  ──────────────────────────────
apply_patch   WRITE     以行级 patch 一次修改多个文件…
read_file     READ      读取文件内容…
...

The default tool set is the workspace bundle (read_file / write_file / edit_file / list_files / search_files / glob_files / apply_patch) plus todos (update_todos / list_todos); the flags above add capabilities. (MCP tools attach at run time, so lithe tools lists them only after a session has started the servers.)

Colors

Output is colored when stdout is a TTY and NO_COLOR is unset; --color / --no-color force either way. Output rendering itself stays dependency-free — plain text degrades cleanly through pipes and cron. Interactive input (the chat prompt and the setup wizard) is prompt_toolkit: wide-character-safe editing, bracketed-paste handling, star-echoed API keys, inline wizard validation, and persistent history.

Where things land

Design notes

• The CLI is a thin host: it supplies tools, a system prompt, and the kernel's JsonlRunStore; everything else (ReAct loop, streaming, budgets, replay, undo engine) is reused from lithe.
• End-to-end behavior is tested offline against a scripted transport — no test spends tokens.
• python -m lithe_cli works alongside the lithe console script.

License

MIT