cligen

A Crystal shard that generates CLI parsers from class definitions using annotations and macros. Define your commands as classes; cligen builds the runtime parse tree.

How It Works

Subclass CliGen::Command, annotate your instance variables with @[CliGen::Argument] or @[CliGen::Selection], and register the command with an CliGen::App. At compile time, macros inspect the annotations and generate typed Flag(T) objects; at runtime, CliGen::App.process walks the CommandNode tree to route arguments, populate your command instance, and dispatch to the right method.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     cligen:
       git: https://git.arcanium.tech/tristan/cligen
   

2. Run shards install

Usage

require "cligen"

@[CliGen::CommandInfo(description: "Greet someone")]
class Greet < CliGen::Command
  @[CliGen::Argument(short: "-n", long: "--name VALUE", description: "Name to greet")]
  @name : String = "world"

  def main
    puts "Hello, #{@name}!"
  end
end

CliGen::App.process

$ myapp --name Alice
Hello, Alice!

Full API documentation and design notes are in design.adoc.

Development

# Type-check without running
crystal build src/cligen.cr --no-codegen

# Run specs
crystal spec

AI Assistance Disclosure

This project uses Claude Code as a development aid — specifically for catching bugs, spotting typos, reviewing implementations, and talking through design decisions. All architecture decisions, code, and design are written by the author. Claude is used the way one might use a second pair of eyes on a diff, not as a code generator.

CLAUDE.md at the repo root documents the project structure for Claude's context. .claude/ holds project-level Claude Code settings.

Contributors

• Tristan Ancelet - creator and maintainer