zli

### 📟 zli - a blazing-fast CLI framework for Zig.

Build modular, ergonomic, and high-performance CLIs with ease.

Batteries included. [ZLI reference docs](https://xcaeser.github.io/zli)

[![Tests](https://github.com/xcaeser/zli/actions/workflows/main.yml/badge.svg)](https://github.com/xcaeser/zli/actions/workflows/main.yml)
[![Zig Version](https://img.shields.io/badge/Zig_Version-0.17.0-orange.svg?logo=zig)](README.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-lightgrey.svg?logo=cachet)](LICENSE)
[![Built by xcaeser](https://img.shields.io/badge/Built%20by-@xcaeser-blue)](https://github.com/xcaeser)
[![Version](https://img.shields.io/badge/ZLI-v7.0.0-green)](https://github.com/xcaeser/zli/releases)

## 🚀 Features

- Modular commands & subcommands
- Fast flag parsing (`--flag`, `--flag=value`, shorthand `-abc`)
- Type-safe support for `bool`, `int`, `string`
- Named positional arguments with `required`, `optional`, `variadic`
- Variadic args can keep parsing flags after the positionals (`passthrough = false`)
- Repeated flags (`ctx.flagValues`) and given-vs-default (`ctx.isFlagSet`)
- Errors on a separate writer (`error_writer`), help stays on `writer`
- Auto help/version/deprecation handling
- Pretty help output with aligned flags & args
- Your own message at the end of a command's help (`help_footer`)
- Spinners for a more interactive experience
- Usage hints, context-aware

## 📦 Installation

```sh
zig fetch --save=zli https://github.com/xcaeser/zli/archive/v7.0.0.tar.gz
```

Add to your `build.zig`:

```zig
const zli_dep = b.dependency("zli", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("zli", zli_dep.module("zli"));
```

## 🌱 Single-file Quick Start

Start with one `src/main.zig`: initialize the root command, add a flag, add a subcommand, then run it.

```zig
const std = @import("std");
const Io = std.Io;
const zli = @import("zli");

pub fn main(init: std.process.Init) !void {
    const io = init.io;

    var wbuf: [1024]u8 = undefined;
    var stdout_writer = Io.File.Writer.init(.stdout(), io, &wbuf);
    const stdout = &stdout_writer.interface;
    defer stdout.flush() catch {};

    var rbuf: [1024]u8 = undefined;
    var stdin_reader = Io.File.Reader.init(.stdin(), io, &rbuf);
    const stdin = &stdin_reader.interface;

    const init_options = zli.InitOptions{
        .allocator = init.gpa,
        .io = io,
        .writer = stdout,
        .reader = stdin,
    };

    const root = try zli.Command.init(init_options, .{
        .name = "hello",
        .description = "A tiny zli app",
        .version = .{ .major = 0, .minor = 1, .patch = 0, .pre = null, .build = null },
    }, showHelp);

    try root.addFlag(.{
        .name = "verbose",
        .shortcut = "v",
        .description = "Print more details",
        .type = .Bool,
        .default_value = .{ .Bool = false },
        .persistent = true,
    });

    const greet = try zli.Command.init(init_options, .{
        .name = "greet",