cliffy

Describe a command-line tool in YAML and get a real Python CLI.

cliffy reads a manifest that lists your commands, their parameters and the code each one runs, and generates a Typer application from it. Command bodies are plain Python, and any line that starts with $ runs as a shell command.

Documentation: https://jaykv.github.io/cliffy/

Example

Install cliffy (Python 3.11 to 3.15):

$ pip install cliffy

Write a manifest:

# hello.yaml
name: hello
version: 0.1.0
help: Hello world!

commands:
  shell: $ echo "hello from shell"
  python: print("hello from python")
  greet:
    help: Greet someone by name
    params:
      - name: str!
      - --shout|-s: bool = False
    run: |
      message = f"Hello, {name}!"
      print(message.upper() if shout else message)

Load it and use it:

$ cli load hello.yaml
✨ Generated hello CLI v0.1.0 ✨
$ hello shell
hello from shell
$ hello greet Ada --shout
HELLO, ADA!

What it does

• Python and shell in one place. Run scripts are Python; $ lines become subprocess calls.
• Typed parameters with a short syntax. name: str! is a required argument, --count|-c: int = 1 is an option.
• Groups, aliases and templates. db.create nests a command, delete|rm adds an alias, command templates share params between commands.
• Hot reload. cli dev hello.yaml reloads the CLI every time you save the manifest.
• Built-in tests. Keep assertions next to your commands and run them with cli test.
• One file to ship. cli build hello.yaml packs the CLI and its dependencies into one zipapp. --target script writes a single Python script that declares its dependencies, and --target native compiles an executable that needs nothing installed.

Commands

Command	Description
cli init <name>	Write a manifest template
cli run <manifest> -- <args>	Run a manifest's CLI once, without installing it
cli load <manifest>	Install the CLI as a command in the current environment
cli dev <manifest>	Reload the CLI whenever the manifest changes
cli test <manifest>	Run the tests defined in the manifest
cli build <manifest>	Build one file to ship: a zipapp, a script or a native executable
cli render <manifest>	Print the generated Python code
cli validate <manifest>	Check a manifest and the code generated from it
cli docs <manifest>	Generate documentation for the CLI
cli list, info, update, remove	Manage loaded CLIs
cli ai generate, cli ai ask	Draft manifests with an LLM (needs the ai extra)
cli ai llms-txt	Print cliffy's documentation as one text file for a coding agent (no extra needed)

Every command and option is described in the CLI reference.

Install options

$ pip install cliffy               # core
$ pip install "cliffy[rich]"       # rich-click help for the cli command and for Click-backend CLIs
$ pip install "cliffy[ai]"         # AI commands, built on pydantic-ai
$ uvx cliffy run hello.yaml greet Ada   # run without installing

See Installation for details.

Learn more

• Quickstart: build a complete CLI step by step
• Guides: params, groups, templates, includes, vars, shell commands, testing, building
• Manifest reference: every key of the format
• Examples: the manifests in examples/
• Changelog and migration notes
• Contributing

Similar tools

• Bashly generates Bash CLIs from YAML.
• Fire generates CLIs from Python objects.

License

MIT