Metadata-Version: 2.5
Name: cliffy
Version: 0.7.0
Summary: $ cli load from.yaml
Project-URL: Homepage, https://github.com/jaykv/cliffy
Project-URL: Documentation, https://jaykv.github.io/cliffy/
Project-URL: Repository, https://github.com/jaykv/cliffy
Project-URL: Issues, https://github.com/jaykv/cliffy/issues
Project-URL: Changelog, https://github.com/jaykv/cliffy/releases
Author-email: Jay <jay.github0@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,click,generator,manifest,shell,typer,yaml,zipapp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.2.1
Requires-Dist: deepmerge>=2.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: packaging>=24.2
Requires-Dist: pybash>=0.4.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: shiv>=1.0.8
Requires-Dist: typer>=0.24.0
Requires-Dist: watchdog>=6.0.0
Provides-Extra: ai
Requires-Dist: pydantic-ai>=2.0.0; extra == 'ai'
Provides-Extra: rich
Requires-Dist: rich-click>=1.9.0; extra == 'rich'
Description-Content-Type: text/markdown

![cliffy logo](https://raw.githubusercontent.com/jaykv/cliffy/main/docs/images/logo.svg)

[![CI](https://img.shields.io/github/actions/workflow/status/jaykv/cliffy/python-app.yaml?branch=main)](https://github.com/jaykv/cliffy/actions)
[![PyPI](https://img.shields.io/pypi/v/cliffy)](https://pypi.org/project/cliffy/)
[![Python versions](https://img.shields.io/pypi/pyversions/cliffy)](https://pypi.org/project/cliffy/)
![License](https://img.shields.io/github/license/jaykv/cliffy)
[![codecov](https://codecov.io/github/jaykv/cliffy/graph/badge.svg?token=84SM8XD5IW)](https://codecov.io/github/jaykv/cliffy)
[![Documentation](https://img.shields.io/badge/docs-jaykv.github.io%2Fcliffy-8A2BE2)](https://jaykv.github.io/cliffy/)

# 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](https://typer.tiangolo.com/) 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):

```console
$ pip install cliffy
```

Write a manifest:

```yaml
# 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:

```console
$ 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) |

Every command and option is described in the
[CLI reference](https://jaykv.github.io/cliffy/reference/cli/).

## Install options

```console
$ 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](https://jaykv.github.io/cliffy/installation/) for details.

## Learn more

- [Quickstart](https://jaykv.github.io/cliffy/quickstart/): build a complete CLI step by step
- [Guides](https://jaykv.github.io/cliffy/guides/manifest-basics/): params, groups, templates,
  includes, vars, shell commands, testing, building
- [Manifest reference](https://jaykv.github.io/cliffy/reference/manifest/): every key of the format
- [Examples](https://jaykv.github.io/cliffy/reference/examples/): the manifests in
  [`examples/`](examples/)
- [Changelog](https://jaykv.github.io/cliffy/project/changelog/) and
  [migration notes](https://jaykv.github.io/cliffy/project/migration/)
- [Contributing](https://jaykv.github.io/cliffy/project/contributing/)

## Similar tools

- [Bashly](https://github.com/DannyBen/bashly) generates Bash CLIs from YAML.
- [Fire](https://github.com/google/python-fire) generates CLIs from Python objects.

## License

[MIT](LICENSE)
