Chilli

A microframework for creating command-line applications in Zig

---

Chilli is a command-line interface (CLI) framework for Zig. It turns a declarative description of commands, flags, and positional arguments into a parser, help generator, and dispatcher, with zero external dependencies and minimal boilerplate.

Features

• Provides a declarative API for building CLI applications
• Supports nested commands, subcommands, and aliases
• Provides type-safe parsing for flags, positional arguments, and environment variables
• Supports generating automatic --help and --version output with custom sections
• Uses a shared context to pass application state
• Written in pure Zig with no external dependencies

See the ROADMAP.md for the list of implemented and planned features.

Important

Chilli is in early development, so bugs and breaking changes are expected. Please use the issues page to report bugs or request features.

---

Getting Started

You can add Chilli to your project and start using it by following the steps below.

Installation

Run the following command in the root directory of your project to download Chilli:

zig fetch --save=chilli "https://github.com/CogitatorTech/chilli/archive/<branch_or_tag>.tar.gz"

Replace <branch_or_tag> with the desired branch or tag, like main (for the development version) or v0.3.0 (for the specified release version). This command will download Chilli and add it to Zig's global cache and update your project's build.zig.zon file.

Zig version supported by the main releases of Chilli:

Zig	Chilli Tags
0.16.0	v0.3.x
0.15.x	v0.2.x

The main branch normally tracks the latest (non-developmental) Zig release.

Adding to Build Script

Next, modify your build.zig file to make Chilli available to your build target as a module.

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 1. Get the dependency object from the builder
    const chilli_dep = b.dependency("chilli", .{});

    // 2. Create a module for the dependency
    const chilli_module = chilli_dep.module("chilli");

    // 3. Create your executable module and add chilli as import
    const exe_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    exe_module.addImport("chilli", chilli_module);

    // 4. Create executable with the module
    const exe = b.addExecutable(.{
        .name = "your-cli-app",
        .root_module = exe_module,
    });

    b.installArtifact(exe);
}

Using Chilli in an Application

Finally, you can @import("chilli") and start using it in your Zig application.

const std = @import("std");
const chilli = @import("chilli");

// A function for our command to execute
fn greet(ctx: chilli.CommandContext) !void {
    const name = try ctx.getFlag("name", []const u8);
    const excitement = try ctx.getFlag("excitement", u32);

    std.debug.print("Hello, {s}", .{name});
    var i: u32 = 0;
    while (i < excitement) : (i += 1) {
        std.debug.print("!", .{});
    }
    std.debug.print("\n", .{});
}

pub fn main(init: std.process.Init.Minimal) anyerror!void {
    var gpa: std.heap.DebugAllocator(.{}) = .init;
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create the root command for your application
    var root_cmd = try chilli.Command.init(allocator, .{
        .name = "your-cli-app",
        .description = "A new CLI built with Chilli",
        .version = "v0.1.0",
        .exec = greet, // The function to run
    });
    defer root_cmd.deinit();

    // Add flags to the command
    try root_cmd.addFlag(.{
        .name = "name",
        .shortcut = 'n',
        .description = "The name to greet",
        .type = .String,
        .default_value = .{ .String = "World" },
    });
    try root_cmd.addFlag(.{
        .name = "excitement",
        .type = .Int,
        .description = "How excited to be",
        .default_value = .{ .Int = 1 },
    });

    // Hand control over to the framework
    try root_cmd.run(init.args, null);
}

You can now run your CLI application with the --help flag to see the output below:

$ ./your-cli-app --help
A new CLI built with Chilli
Version: v0.1.0

Usage:
  your-cli-app [flags]

Flags:
  -h, --help        Shows help information for this command [Bool] (default: false)
      --version     Print version information and exit [Bool] (default: false)
  -n, --name        The name to greet [String] (default: "World")
      --excitement  How excited to be [Int] (default: 1)

---

Documentation

You can find the full API documentation for the latest release of Chilli here.

Alternatively, you can use the make docs command to generate the API documentation for the current version of Chilli from the source code. This will generate HTML documentation in the docs/api directory, which you can serve locally with make serve-docs and view in your web browser at http://localhost:8000.

Examples

Check out the examples directory for examples of how Chilli can be used to build a variety of CLI applications.

---

Contributing

See CONTRIBUTING.md for details on how to make a contribution.

License

Chilli is licensed under the MIT License (see LICENSE).

Acknowledgements

• The logo is from SVG Repo with some modifications.