Metadata-Version: 2.4
Name: typer-cheatsheet-command
Version: 0.2.0
Summary: A pluggable cheatsheet command for Typer applications.
Keywords: typer,cli,command-line,cheatsheet
Author: Martín Gaitán
Author-email: Martín Gaitán <gaitan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: typer>=0.27.1
Requires-Dist: rich>=13.8.0
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/mgaitan/typer-cheatsheet-command
Project-URL: Documentation, https://github.com/mgaitan/typer-cheatsheet-command#readme
Project-URL: Changelog, https://github.com/mgaitan/typer-cheatsheet-command/releases
Project-URL: Repository, https://github.com/mgaitan/typer-cheatsheet-command
Project-URL: Issues, https://github.com/mgaitan/typer-cheatsheet-command/issues
Project-URL: Funding, https://github.com/sponsors/mgaitan
Description-Content-Type: text/markdown

# Typer Cheatsheet Command

A pluggable `cheatsheet` command for your Typer applications to visualize their command tree structure.

This library provides a `cheatsheet` subcommand that you can easily integrate into any existing Typer application. It automatically inspects your Typer application and its subcommands/groups to generate a clear, tree-like representation, making it easier for users to understand available commands.

It traverses the command tree generated by Typer and can also emit a versioned JSON description with command parameters for agents and tooling.

## Installation

You can install this library directly from GitHub using `uv`

```bash
uv add git+https://github.com/mgaitan/typer-cheatsheet-command.git
```

### Demo

You can run the demo application included in this repository to see the `cheatsheet` command in action:

```bash
uvx typer-cheatsheet-command cheatsheet
```

This will output a tree structure of the demo (dummy) application's commands:

![Typer Cheatsheet Command Tree](./cli_2025-10-30.svg)

<!--
using rich capture
rich-capture "uvx typer-cheatsheet-command cheatsheet" --hide-command
-->


### Integrating into your Typer application

To add the `cheatsheet` command to your own Typer application, simply import the `register_cheatsheet_command` function and call it with your `typer.Typer` instance.

First, ensure `typer-cheatsheet-command` is installed in your project's environment.

Then, in your main application file (e.g., `main.py`):

```python
# main.py
import typer
from typer_cheatsheet_command.cheatsheet_command import register_cheatsheet_command

app = typer.Typer(name="MyCoolApp", help="A cool command-line application.")


@app.command()
def hello(name: str = "World"):
    """Say hello to someone."""
    print(f"Hello {name}!")


users_app = typer.Typer(help="Manage users.")


@users_app.command("create")
def create_user(username: str):
    """Creates a new user."""
    print(f"Creating user {username}")


app.add_typer(users_app, name="users")

# Register the cheatsheet command
register_cheatsheet_command(app)

if __name__ == "__main__":
    app()
```

Now, when you run your application, the `cheatsheet` command will be available:

```bash
uv run main.py cheatsheet
```

This would produce an output similar to:

```
╭─ Cheatsheet ───────────────────────────────────────────────────────────────╮
│ MyCoolApp                                                                  │
│ ├── hello: Say hello to someone.                                           │
│ ├── cheatsheet: Show the command tree structure of the application.        │
│ └── users: Manage users.                                                   │
│     └── create: Creates a new user.                                        │
╰────────────────────────────────────────────────────────────────────────────╯
```

By default, the command is registered as `cheatsheet`. If you want to use a different name for the subcommand, you can set it explicitly

```python
register_cheatsheet_command(app, command_name="cheat")
```

The command description is configurable and may contain multiple lines:

```python
register_cheatsheet_command(
    app,
    description="""Show every available command.

    Includes nested groups and their parameters.
    """,
)
```

### JSON output

Use JSON when another program needs to discover commands, options, arguments, and nested groups:

```bash
uv run main.py cheatsheet --output json
```

Hidden commands are excluded by default. Pass `--show-all` to include them in either output format.

The same data is available from Python without registering a command:

```python
from typer_cheatsheet_command import get_command_tree

command_tree = get_command_tree(app)
```
