# Xclif

[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![codecov](https://codecov.io/gh/ThatXliner/xclif/branch/main/graph/badge.svg)](https://codecov.io/gh/ThatXliner/xclif)

[![CI](https://github.com/ThatXliner/xclif/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ThatXliner/xclif/actions/workflows/ci.yml)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/xclif)](https://pypi.org/project/xclif)
[![PyPI](https://img.shields.io/pypi/v/xclif)](https://pypi.org/project/xclif)
[![PyPI - License](https://img.shields.io/pypi/l/xclif)](#license)

> Xliner's CLI Framework

Read the [Manifesto](MANIFESTO.md) to understand *why* Xclif exists and how it compares to Click, Typer, and argparse.

## Installation

```bash
pip install xclif
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add xclif
```

## Quick Start

Your directory structure *is* your command tree:

```
myapp/
├── __init__.py
├── __main__.py
└── routes/
    ├── __init__.py       →  myapp
    ├── greet.py          →  myapp greet
    └── config/
        ├── __init__.py   →  myapp config
        ├── get.py        →  myapp config get
        └── set.py        →  myapp config set
```

```python
# routes/greet.py
from xclif import command

@command()
def _(name: str, template: str = "Hello, {}!") -> None:
    """Greet someone by name."""
    print(template.format(name))
```

```python
# __main__.py
from xclif import Cli
from . import routes

cli = Cli.from_routes(routes)
if __name__ == "__main__":
    cli()
```

No default → positional argument. Has default → `--template` option. Docstring → help text. Drop a file in the right folder and the command exists.

## Features

- **File-based routing** — directory structure is the command tree
- **Decorator + type-hint API** — function signatures define the CLI contract
- **[Rich](https://github.com/Textualize/rich#readme) integration** — beautiful help pages, formatted errors, progress indicators
- **Built-in logging and verbosity** — `--verbose` / `-v` wired up automatically
- **Config management** — `WithConfig[T]` reads from config files or environment variables (CLI flag > env var > config file > default)
- **Autogenerated shell completions** — bash, zsh, fish
- **Minimal overhead** — custom parser built from scratch for fast startup
- **[ExtendedIO](#extendedio)** — reference arbitrary URLs, zip files, SSH, git repos, and other resources as inputs
- **Automatic plugin discovery** — third-party subcommands via entry points (like Git or cargo)
- **Easy testing** — `command.execute(["greet", "Alice"])` with explicit arg lists, no mocking needed

## Performance

Benchmarked on macOS (Apple Silicon, Python 3.12, 30 iterations + 3 warmup, measured as wall-clock subprocess time).

**Command execution** (ms — lower is better):

| Scenario | Click | Typer | Xclif (`from_routes`) | Xclif (flat) |
|---|---|---|---|---|
| `greet World` | 26.7 | 37.6 | 39.5 | **25.4** ✅ |
| `greet` + options | 26.9 | 36.8 | 40.2 | **25.4** ✅ |
| `config set` | 27.3 | 37.3 | 39.4 | **25.5** ✅ |
| `config get` | 29.1 | 36.8 | 40.6 | **25.4** ✅ |
| `--help` | **28.3** ✅ | 82.2 | 58.5 | 46.2 |
| `greet --help` | **29.0** ✅ | 82.8 | 60.1 | 46.2 |

**Xclif (flat)** uses the decorator API (`Command.command()` / `Command.group()`) instead of `from_routes`, eliminating the package-walker overhead (~14 ms). Command execution lands ~1 ms ahead of Click. The `--help` gap (~17 ms vs Click) is Rich's lazy-import cost.

**`from_routes`** adds ~14 ms for the package walker on top, making it slower than Click on every scenario — the trade-off for zero-registration file-based routing.

To reproduce:

```bash
uv run python benchmarks/bench_frameworks.py --iterations 30
```

## ExtendedIO

ExtendedIO is Xclif's approach to transparent resource access. Instead of limiting CLI inputs to local file paths, ExtendedIO lets commands accept arbitrary URIs — URLs, zip archives, SSH paths, git repositories — and resolves them behind the scenes. The API uses dependency injection to provide a unified interface for accessing these resources.

*Coming soon.*

## Roadmap

### Milestone 1: `0.1.0` — Usable Core

- [x] Option value parsing: `--name Bryan` and `--name=Bryan`
- [x] Boolean flags: `--verbose` sets to `True`
- [x] Short aliases: `-v` for `--verbose` (auto-generated)
- [x] `--` separator for raw positional passthrough
- [x] Variadic positional args (`*files: str`)
- [x] `str`, `int`, `float`, `bool` as argument/option types
- [x] `--help` / `-h` on every command
- [x] `--version` on root command (auto-detected from package metadata)
- [x] Rich-formatted help text with alignment
- [x] `Cli.from_routes()` stable and tested
- [x] `list[str]` for repeated options: `--tag foo --tag bar`
- [x] Proper error messages with friendly, formatted output (includes edit-distance suggestions)
- [ ] `pyproject.toml` finalized and published to PyPI

### Milestone 2: `0.2.0` — Developer Experience

- [ ] `WithConfig[T]` — read from config files (TOML/JSON) and env vars (stub exists, not yet functional)
- [ ] `Annotated[str, Arg(description="...")]` for per-parameter metadata
- [ ] Shell completion generation for bash, zsh, fish (stub exists)
- [ ] Distinct user errors vs developer errors with different output styles
- [ ] Documented exit codes

### Milestone 3: `0.3.0` — Power Features

- [ ] Mutually exclusive option groups
- [ ] Cascading global options (opt-in per option)
- [ ] Pre/post command hooks (middleware for auth, logging, etc.)
- [ ] Plugin system: third-party type converters, custom implicit options
- [ ] ExtendedIO

### Non-goals

- Database access or application-level business logic
- Supporting Python < 3.12 (we use `type` statements, generics syntax, etc.)
- A GUI or TUI framework — Xclif is strictly for text CLIs
- Automatic retry, rate limiting, or async command execution

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This project is licensed under the [GNU GPL v3+](https://github.com/ThatXliner/xclif/blob/main/LICENSE.txt).

In short, this means you can do anything with it (distribute, modify, sell) but if you were to publish your changes, you must make the source code and build instructions readily available.

If you are a company using this project and want an exception, email [thatxliner@gmail.com](mailto:thatxliner@gmail.com).
