Skip to content

carapace-sh/carapace-bin / skills/typer

Use when building CLI applications with fastapi/typer — creating commands, defining CLI arguments and options, type-hint-driven parameter parsing, callbacks, context, help customization, shell completion, testing, packaging, or Typer internals. Triggers on: "typer", "typer.run", "typer.Typer", "typer app", "typer command", "typer argument", "typer option", "typer callback", "typer context", "Annotated", "typer.Argument", "typer.Option", "typer.Context", "CliRunner", "add_typer", "rich_markup_mode", "typer completion", "typer autocompletion", "typer echo", "typer test", "typer package", "typer click", "get_command".

FileKindSize
SKILL.mdskill md5.1 KB
references/commands.mdmarkdown6.4 KB
references/completion.mdmarkdown4.3 KB
references/context.mdmarkdown4.9 KB
references/help-output.mdmarkdown4.5 KB
references/internals.mdmarkdown7.4 KB
references/package.mdmarkdown2.8 KB
references/parameter-types.mdmarkdown5.6 KB
references/parameters.mdmarkdown6.9 KB
references/testing.mdmarkdown3.2 KB

references/package.md

View on GitHub
# Packaging and Distributing a Typer CLI

Making a Typer app installable: `pyproject.toml` scripts, `python -m` support, wheels, and publishing.

> **Source of truth**: <https://typer.tiangolo.com/tutorial/package/>. For project structure basics, see [commands.md](commands.md).

## Project Structure

```text
myproject/
├── pyproject.toml
├── README.md
└── src/
    └── myproject/
        ├── __init__.py
        ├── main.py        # app = typer.Typer() lives here
        └── __main__.py    # for python -m support
```

The tutorial uses `uv init --package` to scaffold this layout.

## The Entry Point Script

Map a command name to the app object in `pyproject.toml`:

```toml
[project]
name = "myproject"
dependencies = ["typer"]

[project.scripts]
myproject = "myproject.main:app"

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
```

After `uv pip install -e .` (or `pip install -e .`), the `myproject` command invokes the app. The target can be a `typer.Typer()` instance or any callable — Typer apps are callable.

## `python -m` Support

```python
# src/myproject/__main__.py
from myproject.main import app

app()
```

Then `python -m myproject` works identically to the installed script.

## Building and Publishing

```bash
uv build            # or: python -m build  → creates dist/*.whl and *.tar.gz
uv publish          # or: twine upload dist/*
```

Users install with `pip install myproject` (or `uv pip install myproject`) and get the CLI command plus automatic `--install-completion` (see [completion.md](completion.md)). To install a built wheel as an isolated tool: `uv tool install dist/*.whl`.

## Generating Docs

The `typer` command can generate Markdown documentation for your app (it detects the `typer.Typer` app in the module automatically):

```bash
typer myproject.main utils docs --output README.md --name myproject
```

- `myproject.main` — the module (positional PATH_OR_MODULE)
- `utils docs` — the docs subcommand of the `typer` CLI
- `--output` — write Markdown to a file (omit to print to stdout)
- `--name` — program name used in the generated usage lines

## Gotchas

- With `src` layout, editable installs require a modern build backend; `uv` handles this by default.
- `[project.scripts]` points at the **app object**, not a `main()` function — calling `app()` is what runs the CLI. Pointing at a function works too if you use `typer.run`.
- Shell completion does **not** work via `python -m myproject` — completion is tied to the program name, so call the installed script directly.
- Version bumps for publishing: update `version` in `pyproject.toml` (single source of truth).

## References

- <https://typer.tiangolo.com/tutorial/package/>

## Related

- App structure: [commands.md](commands.md)
- Completion installed with the app: [completion.md](completion.md)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall