treeparse

treeparse lets you build CLIs that render as clean, interactive trees in the terminal using Python. It wraps familiar concepts (arguments, options, groups, subcommands, chains) but always presents help and structure as a navigable tree.

Key Features

• Agent toolboxes — hand a CLI to an agent with its purpose only (--stub); the agent discovers the schema on demand via -h or -j. See Agent Toolboxes.
• Tree rendering — every command, group, and option appears in a structured tree view.
• Snake case everywhere — including class and function names (cli, command, group...).
• Groups and inheritance — options and arguments can be inherited by subgroups and commands.
• Chains — compose sequential commands that run in order with merged params.
• Validation & choices — type-checked callbacks, choices, nargs support.
• Themes — several built-in color themes; easy to customize.
• Docs-driven development — this site is a living Fumadocs + DocKB instance. Humans and agents collaborate via kb/comments/.

Quick Example

from __future__ import annotations

from treeparse import cli, command, argument, option


def greet(name: str, excited: bool = False) -> None:
    msg = f"Hello, {name}!"
    print(msg + ("!!!" if excited else ""))


app = cli(
    name="greet",
    help="A friendly greeter.",
    commands=[
        command(
            name="hello",
            help="Say hello.",
            callback=greet,
            arguments=[argument(name="name", arg_type=str)],
            options=[option(flags=["--excited", "-e"], flag=True, help="Add excitement.")],
        ),
    ],
)

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

Run it:

uv run --with-editable . python -m greet hello Alice --excited

Project Links

• GitHub: https://github.com/wr1/treeparse
• Examples live in examples/
• Tests: uv run pytest

Documentation Sections

• Getting Started
• Agent Toolboxes — the purpose-only stub workflow
• Core models: cli, group, command, argument, option, chain
• Examples
• Testing utilities
• Themes and rendering

The full DocKB (fumano) documentation for the docs system itself lives in the internal dev KB (kb/dev/, visible at /dev/ in rich mode when kb/ is present).

This documentation is the source of truth for development. Use the commenting system (when kb/ present) or edit docs/docs/*.mdx directly.