Treeparse

Tree-shaped Python CLI framework with built-in JSON introspection.

Most CLI frameworks focus on execution. Treeparse treats your CLI as both an executable interface and a structured data model — making it ideal for LLM tool schemas, 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

toolbox --json > skill.md

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

Examples

The examples/ directory contains 19 executable demonstrations covering every Treeparse feature (themes, group-level arguments/options, chaining, 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

# 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

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
• Machine-readable CLI definitions (LLM agents, orchestration, docs pipelines)
• Complex nested command hierarchies

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

Documentation (Fumadocs + DocKB)

This project uses docs-driven development following current fumano/DocKB practice.

• Public docs: only ever edit docs/docs/*.mdx

• kb/ lives inside the site: docs/kb/ (next to app/). It is its own git repo.

• Run the docs site (rich mode when docs/kb/ present):

  make docs-dev                 # recommended (local gitignored Makefile)
  # or
  npm --prefix docs install
  npm --prefix docs run dev     # http://localhost:3000
  npm --prefix docs run build
  

See docs/docs/getting-started.mdx, docs/docs/agent-guide.mdx, docs/docs/architecture.mdx, and the fumano skill in wr1skills.

License

MIT