Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sam701/zig-cli
A simple package for building command line apps in Zig
https://github.com/sam701/zig-cli
argument-parser cli zig
Last synced: about 1 month ago
JSON representation
A simple package for building command line apps in Zig
- Host: GitHub
- URL: https://github.com/sam701/zig-cli
- Owner: sam701
- License: mit
- Created: 2022-03-09T17:55:00.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-18T16:57:21.000Z (12 months ago)
- Last Synced: 2023-12-19T11:04:16.770Z (12 months ago)
- Topics: argument-parser, cli, zig
- Language: Zig
- Homepage:
- Size: 99.6 KB
- Stars: 94
- Watchers: 2
- Forks: 10
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-frameworks - zig-cli
- awesome-zig - sam701/zig-cli
- awesome-zig - zig-cli🗒️A simple package for building command line apps in Zig
README
# ZIG-CLI
A simple package for building command line apps in Zig.
Inspired by [urfave/cli](https://github.com/urfave/cli) Go package.
## Features
* command line arguments are parsed into zig values
* long and short options: `--option1`, `-o`
* optional `=` sign: `--address=127.0.0.1` equals `--address 127.0.0.1`
* concatenated short options: `-a -b -c` equals `-abc`
* subcommands: `command1 -option1 subcommand2 -option2`
* multiple option values: `--opt val1 --opt val2 --opt val3`
* enums as option values: `--opt EnumValue1`
* options value can be read from environment variables with a configured prefix
* positional arguments can be mixed with options: `--opt1 val1 arg1 -v`
* stops option parsing after `--`: `command -- --abc` will consider `--abc` as a positional argument to `command`.
* errors on missing required options: `ERROR: option 'ip' is required`
* prints help with `--help`
* colored help messages when TTY is attached
## Usage
```zig
const std = @import("std");
const cli = @import("zig-cli");
// Define a configuration structure with default values.
var config = struct {
host: []const u8 = "localhost",
port: u16 = undefined,
}{};
pub fn main() !void {
var r = try cli.AppRunner.init(std.heap.page_allocator);
// Create an App with a command named "short" that takes host and port options.
const app = cli.App{
.command = cli.Command{
.name = "short",
.options = &.{
// Define an Option for the "host" command-line argument.
.{
.long_name = "host",
.help = "host to listen on",
.value_ref = r.mkRef(&config.host),
},
// Define an Option for the "port" command-line argument.
.{
.long_name = "port",
.help = "port to bind to",
.required = true,
.value_ref = r.mkRef(&config.port),
},
},
.target = cli.CommandTarget{
.action = cli.CommandAction{ .exec = run_server },
},
},
};
return r.run(&app);
}
// Action function to execute when the "short" command is invoked.
fn run_server() !void {
// Log a debug message indicating the server is listening on the specified host and port.
std.log.debug("server is listening on {s}:{d}", .{ config.host, config.port });
}
```
### Using with the Zig package manager
See the [`standalone`](./examples/standalone) example in the `examples` folder.
## Printing help
See [`simple.zig`](./examples/simple.zig)
```
$ ./zig-out/bin/simple sub1 --help
USAGE:
abc 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 this is the IP address
--int this is an int
--bool this is a bool
--float this is a float
-h, --help Prints help information
```
## License
MIT