Metadata-Version: 2.4
Name: lithe-cli
Version: 0.1.0
Summary: Command-line interface for the lithe agent kernel: chat, one-shot runs, undo, and run inspection.
License: MIT License
        
        Copyright (c) 2026 betaloop contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: agent,llm,react,cli,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lithe>=0.9.5
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# lithe-cli

[![PyPI](https://img.shields.io/pypi/v/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
[![Python](https://img.shields.io/pypi/pyversions/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)
[![License: MIT](https://img.shields.io/pypi/l/lithe-cli.svg)](https://pypi.org/project/lithe-cli/)

**lithe-cli** is the command-line interface for
[lithe](https://pypi.org/project/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,
run one-shot tasks, inspect stored runs, and undo a run's mutations.

```bash
pip install lithe-cli
```

## Configure

There is no default endpoint — the CLI refuses to run rather than silently
hitting some third-party URL. Point it at any OpenAI-compatible endpoint:

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

Flags (`--api-key`, `--base-url`, `--model`) override the environment.
`LITHE_HOME` (default `~/.lithe`) locates the run store; the agent's
workspace defaults to the current directory (`--workspace` to change).

## Use

### One-shot task

```bash
$ cd my-project
$ lithe run "总结 README.md 的要点，存到 SUMMARY.md"
  ⚒ read_file {"path": "README.md"}
  ✓ 已读取 README.md（120 行）
  ⚒ write_file {"path": "SUMMARY.md", "content": "..."}
  ✓ 写入 SUMMARY.md
已把要点写入 SUMMARY.md。
```

`--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

```bash
$ lithe chat
lithe 0.1.0 — /exit 退出，输入任务开始。
lithe> 把 a.txt 改成三行待办清单
  ⚒ write_file {"path": "a.txt", ...}
  ✓ 写入 a.txt
已完成。
lithe> /exit
```

History carries across turns within a session (each turn is its own run in
the store, replayed as context for the next).

### Undo a run

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

```bash
$ lithe runs                     # find the run
abc123def456   done        steps=3  ...
$ lithe undo abc123def456
已撤销 2 个操作（run abc123def456）
```

A file the run created is deleted; a file it overwrote is restored.

### Inspect

```bash
$ lithe runs                     # stored runs (newest last)
$ lithe log abc123def456         # messages + actions of one run
```

### Tools

```bash
$ lithe tools                    # what the agent can do
apply_patch      WRITE  以行级 patch 一次修改多个文件...
edit_file        WRITE  局部替换文件中的文本...
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`).
`--download` additionally grants `download_file` — the SSRF-guarded,
size-capped network fetch — for runs and chats.

## Where things land

| Path | Contents |
| --- | --- |
| current dir (or `--workspace`) | the agent's sandboxed workspace — every tool path resolves strictly inside it |
| `~/.lithe/runs` (or `--store`) | JSONL run store: messages, actions, undo records |
| `~/.lithe/runs/todos-<user>.json` | the agent's task list |

## 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
