zig-cli

A simple, extensible command-line interface (CLI) tool written in Zig. This project demonstrates basic CLI functionality including command parsing, option handling, and extensible command structure.

Features

• Command Parsing: Supports multiple commands with clean syntax
• Option Handling: Short (-n) and long (--name) option formats
• Extensible Architecture: Easy to add new commands and options
• Error Handling: Comprehensive error handling for various CLI scenarios
• Debug Mode: Optional debug output for development

Installation

Prerequisites

• Zig 0.15.0 or higher

Building

1. Clone or download the project
2. Navigate to the project directory
3. Build the executable:

zig build

This will create an executable in zig-out/bin/zig-cli.

Running

You can run the CLI directly using Zig:

zig build run -- [arguments]

Or run the built executable:

./zig-out/bin/zig-cli [arguments]

Usage

Basic Syntax

zig-cli <command> [options]

Available Commands

hello

Greets someone with an optional name.

Options:

• -n, --name <value>: Name to greet (optional, defaults to "World")

Examples:

# Basic greeting
zig-cli hello

# Greeting with a name
zig-cli hello --name Alice
zig-cli hello -n Bob

Output:

Hello, World
Hello, Alice
Hello, Bob

help

Displays usage information and available commands.

Example:

zig-cli help

Output:

Usage: zig-cli <command> [options]
Commands:
  hello    Greet someone
  help     Show this help message

Options for hello:
  -n, --name <value>    Name to greet

Dependencies

This project has no external dependencies. It uses only the Zig standard library.

Project Structure

src/
├── main.zig      # Entry point and command definitions
├── cli.zig       # Core CLI parsing and execution logic
└── commands.zig  # Command and option implementations

Development

Adding New Commands

1. Add a new command handler in src/commands.zig
2. Register the command in src/main.zig in the commands array
3. Update the help command to include the new command

Adding New Options

1. Add an option handler in src/commands.zig
2. Register the option in src/main.zig in the options array
3. Associate options with commands using the req and opt fields

Testing

Run the test suite:

zig build test

Troubleshooting

Common Issues

1. "Unknown command" error

   • Ensure you're using a valid command name
   • Check for typos in command names

2. "Unknown option" error

   • Verify option syntax (-n or --name)
   • Ensure options are valid for the specified command

3. Build errors

   • Ensure you have Zig 0.15.0 or higher installed
   • Check that all source files are present

Debug Mode

Enable debug output by modifying the debug parameter in src/main.zig:

try cli.start(&commands, &options, true);

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure all tests pass
6. Submit a pull request

License

This project is open source. Please see individual files for license information.

Roadmap

• Add more built-in commands (e.g., version, config)
• Support for subcommands
• Configuration file support
• Colored output
• Interactive mode
• Plugin system for extending functionality