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

Metadata

Release files for cliffy 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cliffy 0.7.1
File	Size	Uploaded
cliffy-0.7.1.tar.gz	197.2 kB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cliffy 0.7.1
File	Interpreter	ABI	Platform	Reset
cliffy-0.7.1-py3-none-any.whl 118.2 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 315.4 kB

Release files / cliffy-0.7.1.tar.gz

Download URL	cliffy-0.7.1.tar.gz
Size	197.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`c00034cd3ea968861e27630c40efdec00821b19f93529f405c5476a2e8ddcbf3`
BLAKE2b-256 checksum How to use checksums	`537308140001ec3dafe96e51e28fa9acd16e66e889618aca571f27a26136a9d6`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / cliffy-0.7.1-py3-none-any.whl

Download URL	cliffy-0.7.1-py3-none-any.whl
Size	118.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fbf58858b57418069ff0dbbdb045deee7b2f94c971dd5e58114a1c4d9c6392c3`
BLAKE2b-256 checksum How to use checksums	`0c1af14b6133c72bfba82b151f8294d149d3a2b7f93985930c77bb58bb26d29a`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`