Packages on Zigcli

structargs

Sat, 21 Oct 2023 12:04:40 +0800

structargs turns a Zig struct into a command-line interface.

Instead of building a parser through chained builder calls, you declare one options struct, and structargs derives the flags, defaults, enums, subcommands, and help output from that type at comptime.

Features

The CLI schema lives in one Zig struct:
- normal fields become options
- optional fields and default values become optional flags
- __shorts__ declares short aliases
- __messages__ declares help text
Nested subcommands are declared with __commands__: union(enum)
Help and usage text are generated from the same type definition
--version support is enabled through version_string
print_help_on_error can print stderr help before returning parse errors
Supported option value types include:
- All primitive types, such as i8, u16, f32, bool
- []const u8
- Enum

pretty-table

Sat, 17 Aug 2024 17:48:29 +0800

pretty-table provides two table types plus one owning helper:

Table(N) — fixed-size rows and fixed column count, both known at comptime.
Table(N).Owned — runtime row collection for Table(N), while keeping the same fixed column count.
RuntimeTable — both row count and column count are driven at runtime.

The key constraint is Zig's comptime generics: Table(N) requires N to be a compile-time constant. If the column count comes from runtime data (e.g. parsing a CSV header), RuntimeTable is the only option.

csv

Sun, 22 Mar 2026 16:20:00 +0800

csv parses CSV-style delimited text into rows and fields.

With the default comma delimiter, parseDocument() implements RFC 4180 record and quoted-field parsing, including embedded CRLF, doubled-quote escaping, consistent field counts, and explicit parse errors for malformed input.

It also supports a few explicit extensions: alternate delimiters, optional empty-line skipping, and LF-only line endings.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


const std = @import("std");
const zigcli = @import("zigcli");
const csv = zigcli.csv;

const allocator = std.heap.page_allocator;
const input =
 "name,age,city\r\n" ++
 "alice,30,beijing\r\n" ++
 "bob,25,\"new york\"\r\n";

var document = try csv.parseDocument(allocator, input, .{
 .delimiter = ',',
});
defer document.deinit(allocator);

for (document.rows) |row| {
 std.debug.print("{s}\n", .{row[0]});
}

API

`parseLine(allocator, line, delimiter)`

Parse one line and return a newly allocated slice of fields.

`parseDocument(allocator, input, options)`

Parse a whole input buffer and return a Document:

rows: parsed rows
num_cols: column count inferred from the first parsed row

Malformed input returns a parse error such as error.InvalidQuotedField, error.InvalidRecordTerminator, error.InconsistentFieldCount, or error.UnclosedQuotedField.

Document owns the row and field storage. Call document.deinit(allocator) when you are done with it.

gitignore

Fri, 20 Mar 2026 08:45:00 +0800

Features

Full .gitignore spec support: *, ?, [abc], **/, negation (!)
Recursive .gitignore filtering via GitignoreStack (per-directory layers)
Pure Zig implementation — no libc fnmatch dependency
Last-match-wins semantics across all layers

API

`Gitignore`

Parse a single .gitignore file and match paths against it.

1
2
3
4
5
6
7
8
9


const zigcli = @import("zigcli");
const gitignore = zigcli.gitignore;

var gi = try gitignore.Gitignore.init(allocator, content);
defer gi.deinit();

if (gi.shouldIgnore("build/output.o", false)) {
 // path is ignored
}

`GitignoreStack`

Manage a stack of .gitignore layers for recursive directory walks. Each layer is anchored to its directory, and patterns are evaluated with correct relative paths.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


const zigcli = @import("zigcli");
const gitignore = zigcli.gitignore;

var stack = gitignore.GitignoreStack.init();
defer stack.deinit(allocator);

// Push a layer when entering a directory.
const pushed = try stack.tryPushDir(dir, rel_dir, allocator);

if (stack.shouldIgnore(rel_path, is_dir)) {
 // path is ignored
}

// Pop when leaving the directory.
if (pushed) stack.pop(allocator);

term

Sat, 21 Mar 2026 21:05:00 +0800

term provides the small terminal-focused building blocks shared by zigcli packages and programs.

Use it when you want reusable ANSI styling, a shared color type, or lightweight terminal capability checks without pulling table rendering into your own code.

Features

Style.Color defines the standard ANSI foreground/background colors, including bright variants
Style combines bold, italic, foreground color, and background color into one reusable value
isTty(file) reports whether a file is attached to an interactive terminal
terminalWidth(file) returns the terminal width when it can be detected, otherwise null
stdoutWidth() is a convenience wrapper for the common stdout case

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const std = @import("std");
const zigcli = @import("zigcli");
const term = zigcli.term;

const stdout = std.fs.File.stdout();
var buffer: [1024]u8 = undefined;
var writer = stdout.writer(&buffer);

const style: term.Style = .{
 .bold = true,
 .fg = .bright_green,
};

try style.writeString(&writer.interface, "OK");
try writer.interface.writeByte('\n');
try writer.interface.flush();

`Style.Color`

Style.Color is the shared ANSI color enum used by pretty-table cell styling and by any program that wants plain colored output.

Available colors:

black, red, green, yellow
blue, magenta, cyan, white
bright variants such as bright_red and bright_cyan

Useful helpers:

toEscapeCode(): foreground color escape sequence
toBgEscapeCode(): background color escape sequence
writeString(writer, text): write colored text and reset afterward
reset: the ANSI reset sequence

1

try term.Style.Color.yellow.writeString(&writer.interface, "warning");

progress

Fri, 17 Apr 2026 11:55:10 +0800

progress renders progress bars and spinners to the terminal. It handles ANSI cursor control, terminal width detection, render throttling, and rate/ETA calculation automatically.

Output is hidden when the target file is not a TTY, so piping or redirecting will not produce garbled escape sequences.

Timing uses a monotonic clock (std.time.Timer), so rate and ETA calculations are immune to wall-clock adjustments.

Quick start

Progress bar

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const std = @import("std");
const zigcli = @import("zigcli");
const progress = zigcli.progress;

var bar = progress.Progress.bar(allocator, .{
 .total = 100,
 .prefix = "download",
 .message = "fetching data",
});
defer bar.deinit();

for (0..100) |_| {
 bar.inc(1);
 try bar.render();
}
try bar.finish();

Output:

download [==========>---------] 55.0% 55/100 27/s ETA 0:01 fetching data

Spinner

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var spinner = progress.Progress.spinner(allocator, .{
 .prefix = "build",
 .message = "compiling",
});
defer spinner.deinit();

for (0..40) |_| {
 spinner.tick();
 try spinner.render();
}
try spinner.finish();

Output:

build | elapsed 0:05 compiling