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

Feature	argparse	Click	Typer	Treeparse
Tree-structured help	No	Partial	Partial	Yes
JSON CLI export	No	No	No	Yes
Explicit structural model	No	No	No	Yes
Signature validation	Minimal	No	Partial	Yes

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

Flag	Output
--help, -h	Rich tree, branch-pruned per subcommand
--json, -j	Full CLI structure as JSON
--version, -V	Auto-detected from package metadata, or set with version= on cli

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

Model	Purpose
cli	Root — reusable as a subgroup in another cli
group	Namespace with optional fold=True to collapse in help, or default="cmd" to route unknown tokens to a child command
command	Executable action with a callback
chain	Runs multiple commands in sequence
argument	Positional — <ARG> required, [ARG] optional (nargs="?"/"*")
option	Named flag, with optional inheritance to child commands

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