zli

zli is a CLI argument parsing module for Zig. The aim is to provide CLI parameters in a simple, declarative way and have zli parse them as well as generate --help and --version flags and usage error messages.

features

short options + boolean short options be be given in clusters e.g. ls -lhF + the last short option in a cluster may take an argument as the next command line word, e.g. tar -xf file.tar
long options + arguments to long options may be the next command line word or separated from the option by an equals sign
automatic handling of --help and --version options
typed argument parsing + supports booleans, floats, integers, enums, []u8 and [:s]u8 (for some sentinel s)
git-style subcommands

usage

A usage example is given by src/main.zig. CLI parameters are declared like so:

const arg_spec = [_]zli.Arg{
    .{
        .name = .{ .long = .{ .full = "file", .short = 'f' } },
        .short_help = "file name",
        .type = []const u8,
    },
    .{
        .name = .{ .short = 'a' },
        .short_help = "short only option",
        .type = u8,
    },
    .{
        .name = .{ .long = .{ .full = "a-really-long-arg" } },
        .short_help = "How does this look?",
        .type = enum { yes, no },
    },
    .{
        .name = .{ .long = .{ .full = "complicated", .short = 'k' } },
        .short_help = "This option is very complicated and the 'short' help message included here is so long that we want some nice line breaking to occur",
    },
    .{
        .name = .{ .long = .{ .full = "flag-1", .short = '1' } },
        .short_help = "just a flag",
        .type = bool,
    },
    .{
        .name = .{ .short = '2' },
        .short_help = "another flag",
        .type = bool,
    },
};

const version = std.SemanticVersion{
    .major = 0,
    .minor = 0,
    .patch = 0,
};

const Cli = zli.CliCommand("zli-example-app", .{ .parameters = &arg_spec, .version = version });

CLI parameters can then be parsed with try Cli.parse(allocator). The auto-generated help message generated by the example is:

zli-example-app 0.0.0

Options:

  -f, --file                     file name
  -a                             short only option
      --a-really-long-arg        How does this look?
  -k, --complicated              This option is very complicated and the 'short' help message
                                   included here is so long that we want some nice line
                                   breaking to occur
  -1, --flag-1                   just a flag
  -2                             another flag
      --help                     Print this help message
      --version                  Print version information

which can you can see by running zig build run -- --help.

To use zli in a project you can use the Zig package manager by using https://github.com/dweiller/zli/archive/[[COMMIT-SHA]].tar.gz as the dependency URL and then grabbing the 'zli' module, e.g.:

add zli to your build.zig.zon:

zig fetch --save=zli https://github.com/dweiller/zli/archive/[[COMMIT-SHA]].tar.gz

build.zig:

pub fn build(b: *std.Build) void {

    // -- snip --

    const exe = ...; // your executable

    const zli = b.dependency("zli").module("zli");
    exe.root_module.addImport("zli", zli);

    // -- snip --
}