zig-cli

A simple package for building command line apps in Zig.

Inspired by urfave/cli Go package.

Features

• Arguments parsed directly into Zig values
• Long and short options: --option, -o
• Optional = sign: --address=127.0.0.1 equals --address 127.0.0.1
• Concatenated short options: -a -b -c equals -abc
• Subcommands: cmd -opt subcmd -opt2
• Multiple option values: --opt val1 --opt val2 --opt val3
• Enums as option values: --opt EnumValue1
• Positional arguments (required and optional), mixed with options: --opt val arg1 -v
• Option values read from environment variables with a configured prefix
• Stops option parsing after --: cmd -- --abc treats --abc as a positional argument
• Errors on missing required options: ERROR: missing required option '--port'
• App version and author metadata
• Built-in --help flag with colored output when a TTY is attached

Usage

API Documentation

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

var config = struct {
    host: []const u8 = "localhost",
    port: u16 = undefined,
}{};

pub fn main(init: std.process.Init) !void {
    var r = cli.AppRunner.init(&init);
    defer r.deinit();

    const app = cli.App{
        .command = cli.Command{
            .name = "server",
            .options = try r.allocOptions(&.{
                .{
                    .long_name = "host",
                    .help = "host to listen on",
                    .value_ref = r.mkRef(&config.host),
                },
                .{
                    .long_name = "port",
                    .help = "port to bind to",
                    .required = true,
                    .value_ref = r.mkRef(&config.port),
                },
            }),
            .target = cli.CommandTarget{
                .action = cli.CommandAction{ .exec = run },
            },
        },
    };
    return r.run(&app);
}

fn run() !void {
    std.log.info("listening on {s}:{d}", .{ config.host, config.port });
}

Installing with the Zig package manager

1. Fetch the package:

# For zig master and zig 0.16
zig fetch --save git+https://github.com/sam701/zig-cli

# For zig 0.15
zig fetch --save git+https://github.com/sam701/zig-cli#zig-0.15

2. Wire it up in build.zig:

const cli_dep = b.dependency("cli", .{});
exe.root_module.addImport("cli", cli_dep.module("cli"));

Help output

See simple.zig for a full example with subcommands.

$ ./zig-out/bin/simple sub1 --help
USAGE:
  simple sub1 [OPTIONS]

another awesome command

this is my awesome multiline description.
This is already line 2.
And this is line 3.

COMMANDS:
  sub2   sub2 help

OPTIONS:
  -i, --ip <IP>         this is the IP address
      --int <VALUE>     this is an int
      --bool            this is a bool
      --float <VALUE>   this is a float
  -h, --help            Prints help information

License

MIT