ItTiger.TigerCli 0.9.4

ItTiger.TigerCli

TigerCli is an opinionated .NET CLI/TUI app framework for command-driven tools. It is intended for developers building utilities, administration tools, developer tooling, and automation that should work well both at a terminal and in scripts.

It combines command-line execution with semi-interactive prompts, command menus, structured output, activity and progress UI, validation, app-provided choices, themes, and a predictable exit-code policy. The same command model can prompt a person when values are missing or fail clearly under --non-interactive when automation must not wait for input.

Command execution follows app <command-path> <positional-arguments> [options]. Framework execution options and contributed global options are app-wide in meaning but still belong after the command path and required positionals. A default/root command has an empty command path, so its shape is app <positional-arguments> [options]. Root informational forms such as app --help remain separate from command execution, and combine with execution options in the same options area (app --help --theme light).

Help is composable: --help, --help-errors, and --help-env can be requested independently or together. --help-env documents TigerCli's rendering variables plus help-only metadata registered by apps and reusable contributions; registration does not make TigerCli read or apply a variable.

Generated help is rendered as full-width themed CliGrid documents. Entries intentionally use a key line followed by an indented description; measured wrapping preserves that indentation, while the theme's Text-over-Background document base paints coherent complete rows. AnsiSink is terminal-bounded by default, so help and other structured output wrap during layout.

Installation

TigerCli currently targets .NET 10.

dotnet add package ItTiger.TigerCli --version 0.9.4

Minimal app

Delegate commands are the smallest way to create a working TigerCli app:

using ItTiger.TigerCli.Commands;
using ItTiger.TigerCli.Terminal;

return await TigerCliApp.CreateBuilder()
    .AddDefaultCommand(static () =>
    {
        TigerConsole.MarkupLine("[Key]Hello[/], [Accent]TigerCli[/]!");
        return TigerCliExitKind.Success;
    })
    .Build()
    .RunAsync(args);

This gives the tool TigerCli's normal command pipeline, framework options, help behavior, rendering, and exit handling without requiring settings or handler classes.

Full command model

Delegate commands are intended for tiny tools, demos, smoke apps, and simple automation. For a larger application, the promoted model separates typed settings, a command handler, and builder registration:

using ItTiger.TigerCli.Commands;
using ItTiger.TigerCli.Terminal;

return await TigerCliApp.CreateBuilder()
    .SetDefaultCommand<GreetCommand>()
    .Build()
    .RunAsync(args);

public sealed class GreetSettings : TigerCliSettings
{
    [TigerCliOption("--name", Required = true, Description = "Name to greet.")]
    public string Name { get; set; } = string.Empty;
}

public sealed class GreetCommand : TigerCliAsyncCommandHandler<GreetSettings>
{
    public override Task<int> ExecuteAsync(GreetSettings settings)
    {
        TigerConsole.MarkupLine(settings.E("[Key]Hello[/], {0}!", settings.Name));
        return Task.FromResult(0);
    }
}

The full model is where typed options and arguments, prompts, providers, validation, selectors, command groups, localization, reusable handlers, and application-specific exit codes belong.

What TigerCli provides

• Command applications with default commands, named commands, command groups, and optional command menus
• Prompted options with text, confirm, select, and multi-select controls
• Application providers for dynamic, validated choices
• Folder and file prompts through TigerCliFolderSelect, TigerCliFileOpen, and TigerCliFileSave
• Structured terminal output with CliList, CliDetails, CliTable, grids, markup, and semantic styles
• Activity dialogs, spinners, cancellation, and progress bars
• Built-in themes plus console, HTML, and test-friendly rendering sinks
• Automation-safe --non-interactive behavior with no surprise prompts
• Handler-visible caller and process cancellation through TigerCliSettings.CancellationToken
• Command-declared raw trailing arguments after -- for literal child-tool pass-through
• Opt-in app contributions for constrained, reusable-library global string options
• Configurable exit-code policy and portable TigerCliExitKind outcomes
• App-level test hosting and deterministic TUI test infrastructure

Related packages

• ItTiger.TigerCli — this package: command apps, prompting, TUI controls, rendering, exit policy, and testing support.
• ItTiger.Core — shared core helpers used by TigerCli; it is installed transitively with this package.
• ItTiger.TigerCli.PngSink — optional deterministic PNG rendering for documentation artifacts, examples, and visual review.

Links

• Project page
• Documentation
• API reference
• Examples and getting started
• GitHub repository
• MIT license

An open-source project by IT Tiger.