Treeparse

Tree-shaped Python CLI framework for building toolboxes you can hand to agents.

Instead of stuffing full tool schemas into an agent's context, give it the toolbox's purpose only — the agent discovers the command tree (-h) or the machine-readable schema (-j) on demand. Treeparse makes this possible by treating your CLI as both an executable interface and a structured data model, which also suits automation workflows and complex nested command hierarchies.

Why Treeparse

Quickstart

pip install treeparse

from treeparse import cli, command, argument

def greet(name: str):
    print(f"Hello {name}")

greet_cmd = command(
    name="greet",
    callback=greet,
    arguments=[argument(name="name", arg_type=str)],
)

app = cli(name="demo", commands=[greet_cmd])

if __name__ == "__main__":
    app.run()

$ python app.py greet Alice
Hello Alice

$ python app.py --help
demo
└── greet
    └── <NAME>

$ python app.py --json
{"name": "demo", "commands": [{"name": "greet", "arguments": [{"name": "name", "type": "str"}]}]}

Workflow

1. Build tool 1

# ink.py
ink = cli(name="ink", help="Annotate figures with Inkscape.")
ink.commands.append(command(
    name="new", help="Open a new blank SVG.", callback=new,
    arguments=[argument(name="name", arg_type=str)],
    options=[option(flags=["--notes-dir", "-d"], arg_type=str, default="notes/draw")],
))

2. Build tool 2

# mind.py
mind = cli(name="mind", help="Build mind maps in Minder.")
mind.commands.append(command(
    name="create", help="Create a new mind map.", callback=create,
    arguments=[argument(name="title", arg_type=str)],
))

3. Plug into a toolbox

# toolbox.py
from treeparse import cli
from ink import ink
from mind import mind

toolbox = cli(name="toolbox", help="Creative toolbox.", subgroups=[ink, mind])

if __name__ == "__main__":
    toolbox.run()

4. Teach the LLM

Hand the agent the purpose only — not the schema:

toolbox --stub > skill.md

toolbox — Creative toolbox.

This is a CLI toolbox. Discover its commands and
full schema on demand:
  toolbox -h   # command tree
  toolbox -j   # machine-readable JSON schema

The agent runs -h or -j itself when (and only when) it needs the schema, keeping its context small.

Human-readable tree

toolbox --help

toolbox                      Creative toolbox.
├── ink                      Annotate figures with Inkscape.
│   └── new <NAME>           Open a new blank SVG.
│       └── --notes-dir, -d  Directory to save SVGs (default: notes/draw)
└── mind                     Build mind maps in Minder.
    └── create <TITLE>       Create a new mind map.

Built-in flags

Two discovery channels: tree for humans, JSON for machines.

Examples

The examples/ directory contains 22 executable demonstrations covering every Treeparse feature (themes, group-level arguments/options, chaining, flat sub-cli toolbox composition, nargs="*"| "+", boolean flags, validation errors, root options, JSON export, custom sort/fold, etc.). They are living documentation and the primary reference for users and LLMs.

They are not installed as part of the package. After pip install treeparse only the core library and the treeparse console script are available.

Recommended development workflow

# Clone and set up (once)
git clone https://github.com/wr1/treeparse.git
cd treeparse
uv sync --dev
uv run pre-commit install   # ruff check --fix + ruff format on every commit

# Run any example with an editable install (no need to touch PYTHONPATH)
uv run --with-editable . python examples/demo.py --help
uv run --with-editable . python examples/all_themes_demo.py --help
python examples/validation_error_demo.py --help   # after the uv command above

# Manual lint/format (same as CI and pre-commit)
uv run ruff check --fix .
uv run ruff format .

The test suite (tests/test_examples.py and test_demo_execution.py) loads the examples via importlib.util.spec_from_file_location and will continue to pass without any changes to packaging.

Models

from treeparse import cli, command, group, argument, option
from treeparse.models.chain import chain

More

• Folding: group(fold=True) collapses to group [...] — drill in with toolbox ink --help
• Default subcommand: group(default="open") routes a bare group, an option flag, or an unknown token to that child command (toolbox ink foo → toolbox ink open foo); explicitly-named subcommands always win
• Inheritance: option(inherit=True) propagates to all child commands
• Validation: callback param names and types checked against CLI definition at startup
• YAML config: cli(yml_config=Path("config.yml")) overrides defaults at runtime
• Themes: theme="github" / "monokai" / "mononeon" / "monochrome"
• Testing: CliRunner for pytest integration

When to Use

Use Treeparse if you need:

• Structured CLI composition
• Toolboxes for LLM agents — purpose-only stubs with schema discovery on demand (--stub, -h, -j)
• Machine-readable CLI definitions (orchestration, docs pipelines)
• Complex nested command hierarchies

Avoid if you only need a simple single-script CLI.

Documentation

Hosted docs: https://wr1.github.io/treeparse/

To work on the docs site locally, see docs/README.md.

License

MIT