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

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