SuperCli 0.1.3

SuperCli

A .NET 10 source-generator-based CLI framework. All command routing and argument parsing is generated at compile time — zero runtime reflection.

Install

dotnet add package SuperCli

That's it. The NuGet package includes both the runtime library and the source generator — no extra configuration needed.

Requires .NET 10+.

Quick Start

1. Install the package

dotnet add package SuperCli

2. Define commands

Mark a class with [Command] to create a command group, and mark methods with [Command] to define sub-commands:

using SuperCli.Attributes;

[Command("calc")]
internal partial class CalcCommand
{
    [Command("add")]
    public void Add(int x, int y)
    {
        Console.WriteLine($"{x} + {y} = {x + y}");
    }

    [Command("mul")]
    public void Multiply(int x, int y)
    {
        Console.WriteLine($"{x} * {y} = {x * y}");
    }
}

3. Bootstrap and run

using SuperCli;

var builder = CliApplication.CreateBuilder();
var app = builder.Build();
return app.Run(args);

4. Execute

dotnet run -- calc add --x 1 --y 2
# Output: 1 + 2 = 3

dotnet run -- calc mul --x 3 --y 4
# Output: 3 * 4 = 12

Defining Commands

Method Parameters

All method parameters become CLI options in --kebab-case. For example, a parameter named outputDir becomes --output-dir on the command line.

[Command("greet")]
public void Greet(string name, int count = 1)
{
    for (int i = 0; i < count; i++)
        Console.WriteLine($"Hello, {name}!");
}

app greet --name Alice --count 3

CancellationToken parameters are automatically excluded from CLI options — the framework injects a token tied to Ctrl+C.

Nested Commands

Nested classes with [Command] create multi-level paths:

[Command("calc")]
internal partial class CalcCommand
{
    [Command("advanced")]
    internal partial class AdvancedCalcCommand
    {
        [Command("pow")]
        public void Power(int x, int y)
        {
            Console.WriteLine($"{x} ^ {y} = {Math.Pow(x, y)}");
        }
    }
}

app calc advanced pow --x 2 --y 10
# Output: 2 ^ 10 = 1024

XML Documentation → Help Text

XML doc comments on command classes and methods are automatically used as help text:

/// <summary>
/// Adds two integers together and prints the result.
/// </summary>
/// <param name="x">The first operand.</param>
/// <param name="y">The second operand.</param>
[Command("add")]
public void Add(int x, int y) { ... }

Global Options

Define a class with [GlobalOptions] and mark properties with [Option]:

[GlobalOptions]
public class MyGlobalOptions
{
    [Option("--verbose", ShortName = "-v")]
    public bool Verbose { get; set; }

    [Option("--output-format", ShortName = "-of")]
    public string OutputFormat { get; set; } = "text";
}

Global options are parsed before command dispatch, are available via DI in command constructors, and appear in help at every level:

app --verbose calc add --x 1 --y 2
app -v -of json calc add --x 1 --y 2

Inject them into any command via constructor:

[Command("calc")]
internal partial class CalcCommand
{
    private readonly MyGlobalOptions _opts;

    public CalcCommand(MyGlobalOptions opts)
    {
        _opts = opts;
    }
}

Filter Pipeline

Filters implement ICommandFilter and act as middleware around command execution:

public class LoggingFilter : ICommandFilter
{
    public async Task HandleAsync(
        CommandExecuteContext context,
        Func<CommandExecuteContext, Task> next)
    {
        Console.WriteLine($"Before: {context.CommandName}");
        await next(context);
        Console.WriteLine($"After: {context.CommandName}");
    }
}

Attach filters with [CommandFilter]:

// Class-level — runs for all methods in this class
[Command("my")]
[CommandFilter<LoggingFilter>]
internal partial class MyCommand
{
    // Method-level — runs for this specific method
    [Command("action")]
    [CommandFilter<ValidationFilter, HappyFilter>]
    public void Action(string name) { ... }
}

Execution Order

Class-level filters → Method-level filters → ParseArgsFilter → Command method

CommandExecuteContext

The context object carries:

Built-in Flags

app --help              # Show all top-level commands
app calc --help         # Show commands under "calc"
app calc add --help     # Show help for "calc add"
app --version           # Print version

Architecture

Source Generator Pipeline
━━━━━━━━━━━━━━━━━━━━━━━━
CommandGenerator (IIncrementalGenerator)
    │
    ├── CommandExtensionEmitter  → CommandExtensions.g.cs
    │   (extract parsed args, invoke command methods)
    │
    ├── CommandArgsEmitter       → CommandArgs.g.cs
    │   (per-command Args classes + ParseArgsFilter)
    │
    ├── CommandFilterEmitter     → CommandFiltersPipelines.g.cs
    │   (middleware chain builder)
    │
    └── CommandDispatchEmitter   → CommandDispatch.g.cs
        (prefix tree → nested switch/case routing)

Build from Source

dotnet build SuperCli.slnx
dotnet run --project src/SuperCli.Demo/SuperCli.Demo.csproj -- calc add --x 1 --y 2

The source generator project (SuperCli.SourceGenerator) targets netstandard2.0 for Roslyn compatibility. If the DLL gets locked by CSharpLanguageServer during build, kill the process and retry.

AI Agent Skill (Claude Code + others)

SuperCli ships a skill that teaches AI coding agents (Claude Code, and any agent that reads .agents/skills/) how to use the framework while you build your CLI. No installer or script is needed — just add the package:

dotnet add package SuperCli

On your next dotnet build, the skill is dropped into .agents/skills/supercli/ at the solution root (or the project directory for single-project builds) and linked into .claude/skills/supercli so Claude Code picks it up automatically; other agents read .agents/ directly. No network call, no manual step. Linking is cross-OS safe: a directory junction on Windows (no admin/Dev Mode needed), a symlink elsewhere, copy as a last resort.

The skill re-syncs on every build, so upgrading the package also updates the skill — no re-install required.

Options (set as MSBuild properties in any referencing project):

The repo also bundles standalone skill/install-skill.sh / install-skill.ps1 scripts if you ever need to install the skill into a project that doesn't reference the package.

License

MIT