XenoAtom.CommandLine

https://github.com/xenoatom/xenoatom.commandline
Admin
XenoAtom.CommandLine is a lightweight, powerful, and NativeAOT-friendly command-line parsing library...
Tokens:97,471
Snippets:781
Trust Score:8.6
License:BSD-2-Clause
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install lunet tool

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/AGENTS.md

Install the lunet dotnet tool globally. Run once before building the site.

```bash
dotnet tool install -g lunet
```

--------------------------------

### Example Response File (args.txt)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Example content of a response file. Demonstrates whitespace separation, quoted values, and comments.

```text
--name John
--port 8080
# This is a comment
"hello world"
```

--------------------------------

### WriteUnknownTokens output example

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Example output for an unknown option error, showing the error message and a suggestion.

```text
[bold red]Error:[/] Unknown option: --verbos
[dim]Did you mean: --verbose[/]
```

--------------------------------

### Help output for greet command

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/getting-started.md

Output of running `greet --help` for the previous example. Shows the Usage line and the options list with their descriptions.

```text
Usage: greet [options]

  -n, --name=NAME            Your NAME
  -a, --age=AGE              Your AGE
  -v, --verbose              Enable verbose output
  -h, -?, --help             Show this message and exit
```

--------------------------------

### Custom Output Renderer Example

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Example implementation of ICommandOutput that renders output as JSON.

```APIDOC
## Custom Output Renderer Example

### Description
Example implementation of ICommandOutput that renders output as JSON.

### Code Example
```cs
public sealed class JsonOutputRenderer : ICommandOutput
{
    public void WriteHelp(Command command, CommandRunConfig runConfig)
    {
        // Access command.Options, command.Arguments, command.SubCommands
        runConfig.Out.WriteLine("{ \"help\": \"" + command.GetFullCommandPath() + "\" }");
    }

    public void WriteError(Command command, CommandRunConfig runConfig, CommandException exception)
    {
        runConfig.Error.WriteLine("{ \"error\": \"" + exception.Message + "\" }");
    }

    public void WriteUnknownTokens(Command command, CommandRunConfig runConfig, UnknownTokenReport report)
    {
        foreach (var token in report.UnknownTokens)
            runConfig.Error.WriteLine("{ \"unknown\": \"" + token.Token + "\" }");
    }

    public void WriteVersion(Command command, CommandRunConfig runConfig, string version)
        => runConfig.Out.WriteLine("{ \"version\": \"" + version + "\" }");

    public void WriteLicenseHeader(Command command, CommandRunConfig runConfig, string licenseText)
        => runConfig.Out.WriteLine(licenseText);
}
```
```

--------------------------------

### Help output for root command

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/commands.md

Output of running 'myexe --help' for the example with the 'commit' sub-command. Shows usage, options, and available commands.

```text
Usage: myexe [options] <command>

  -n, --name=NAME            Your NAME
  -h, -?, --help             Show this message and exit

Available commands:
  commit                     Commit changes
```

--------------------------------

### Help output for commit sub-command

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/commands.md

Output of running 'myexe commit --help' for the example with the 'commit' sub-command. Shows usage, options, and arguments.

```text
Usage: myexe commit [options] <files>*

Options:
  -m, --message=MESSAGE      Commit MESSAGE
  -h, -?, --help             Show this message and exit

Arguments:
  <files>*                   Files to commit
```

--------------------------------

### Help output showing environment variable

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/options.md

Example help output for an option with environment variable fallback, showing the `[env: MY_PORT]` annotation.

```text
  -p, --port=PORT            Server PORT [env: MY_PORT]
```

--------------------------------

### Get completion candidates programmatically

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Shows how to retrieve completion candidates for a partially typed command line using GetCompletions and GetCompletionsForTokens. The first example returns option names, the second returns command names based on token index.

```csharp
var candidates = app.GetCompletions("myexe --na");
// → ["--name"]

var commandCandidates = app.GetCompletionsForTokens(["myexe", "buil"], tokenIndex: 1);
// → ["build"]
```

--------------------------------

### Visual Tier — multi hello --help

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Example output of `multi hello --help` in the visual tier, showing options and arguments sections.

```text
Usage: multi hello [options] <files>*

Options:
  -n, --name=VALUE   This is a name
  -a, --age=AGE      Sets the AGE
  -h, -?, --help     Show this message and exit

Arguments:
  <files>*           Input files
```

--------------------------------

### Combining Multiple Constraints (Fluent Setup)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/validation.md

Fluent API equivalent to the collection initializer version for combining multiple constraints.

```csharp
app.AddMutuallyExclusive("json", "xml");
app.AddMutuallyExclusive("verbose", "quiet");
app.AddRequires("password", "user");
app.AddRequires("tls-cert", "tls-key");
```

--------------------------------

### Wiring Into CommandLine

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Examples of configuring CommandApp with markup or visual output factories, including per-invocation override and standalone visual builder usage.

```APIDOC
## Wiring Into CommandLine

### Description
Examples of configuring CommandApp with markup or visual output factories, including per-invocation override and standalone visual builder usage.

### Markup output (simple)
```csharp
using XenoAtom.CommandLine;
using XenoAtom.CommandLine.Terminal;

var app = new CommandApp("myapp", config: new CommandConfig
{
    OutputFactory = _ => new TerminalMarkupCommandOutput()
});
```

### Visual output (rich)
```csharp
var app = new CommandApp("myapp", config: new CommandConfig
{
    OutputFactory = _ => new TerminalVisualCommandOutput()
});
```

### With options
```csharp
var app = new CommandApp("myapp", config: new CommandConfig
{
    OutputFactory = _ => new TerminalVisualCommandOutput(new TerminalVisualOutputOptions
    {
        UseTableForOptions = true,
        OptionPrototypeStyle = "[green]",
        Theme = Theme.DefaultLight,
    })
});
```

### Per-invocation override
```csharp
command.ShowHelp(new TerminalMarkupCommandOutput());
```

### Standalone visual builder (for fullscreen apps)
```csharp
using var session = Terminal.Open();
Terminal.Run(
    new ScrollViewer(myCommand.ToHelpVisual()).MaxHeight(30),
    onUpdate: () => /* ... */);
```
```

--------------------------------

### Build with dotnet build

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/readme.md

Run this command from the root folder after installing the .NET 10 SDK to build the project in Release configuration.

```console
$ dotnet build src -c Release
```

--------------------------------

### ToHelpVisual extension method

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Extension method that builds a help Visual from a Command. Includes an inline usage example and a fullscreen usage example in the XML documentation.

```csharp
using XenoAtom.Terminal.UI;

namespace XenoAtom.CommandLine.Terminal;

/// <summary>
/// Extension methods for building Terminal.UI visuals from command-line objects.
/// </summary>
public static class CommandTerminalExtensions
{
    /// <summary>
    /// Builds a help <see cref="Visual"/> from the specified command.
    /// </summary>
    /// <param name="command">The command whose help to visualize.</param>
    /// <param name="options">Optional visual builder options.</param>
    /// <returns>A <see cref="Visual"/> that can be written with <c>Terminal.Write(visual)</c>
    /// or embedded in a fullscreen app.</returns>
    /// <example>
    /// <code>
    /// // Inline usage:
    /// Terminal.Write(command.ToHelpVisual());
    ///
    /// // Fullscreen usage:
    /// Terminal.Run(new ScrollViewer(command.ToHelpVisual()), ...);
    /// </code>
    /// </example>
    public static Visual ToHelpVisual(this Command command, TerminalVisualOutputOptions? options = null);
}
```

--------------------------------

### Command line invocation and output for key/value options

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/options.md

Example command line and its output demonstrating how key/value pairs are parsed. The output shows that optional values can be empty (e.g., 'Hello =').

```sh
myexe -DA=B -DHello -IG=F --macro X=Y
```

```text
Macro: A = B
Macro: Hello =
Macro: G = F
Macro: X = Y
```

--------------------------------

### Example invocations with options and arguments

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/arguments.md

Shows two equivalent command lines: one with the option before the arguments and one with the option between them. Both produce the same result because options are extracted first.

```sh
myexe --verbose input.txt output.txt
myexe input.txt --verbose output.txt   # same result — options are extracted first
```

--------------------------------

### Install XenoAtom.CommandLine NuGet package

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/getting-started.md

Adds the XenoAtom.CommandLine package to the project. The library targets net8.0 and later, has zero dependencies, and is compatible with NativeAOT publishing.

```sh
dotnet add package XenoAtom.CommandLine
```

--------------------------------

### Fullscreen Embedding

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

C# example showing how to embed a help visual in a fullscreen terminal UI using `Terminal.Open()`, `ToHelpVisual`, and `Terminal.Run` with a VStack containing Header, ScrollViewer, and Footer.

```csharp
using var session = Terminal.Open();

var helpVisual = myCommand.ToHelpVisual(new TerminalVisualOutputOptions
{
    UseTableForOptions = true,
    OptionPrototypeStyle = "[green]",
});

Terminal.Run(
    new VStack(
        new Header("My Application"),
        new ScrollViewer(helpVisual).Stretch(),
        new Footer("Press Q to quit")
    ),
    onUpdate: () => /* handle input */);
```

--------------------------------

### Enable Response Files with ResponseFileSource

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Adds ResponseFileSource to the command configuration to enable reading arguments from response files. The example also includes a help option and a handler that prints each argument.

```csharp
var app = new CommandApp("myexe")
{
    new HelpOption(),
    new ResponseFileSource(),
    { "<>", "Extra arguments" },
    (ctx, arguments) =>
    {
        foreach (var arg in arguments)
            ctx.Out.WriteLine(arg);
        return ValueTask.FromResult(0);
    }
};
```

--------------------------------

### Format help output with text strings and collection initializer

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Use empty strings for blank lines and plain strings for section headers in a CommandApp collection initializer. This example shows a complete help layout with usage, options, arguments, commands, and a footer.

```csharp
const string _ = "";
var app = new CommandApp("myexe")
{
    new CommandUsage(),
    _,
    "Options:",
    { "v|verbose", "Verbose", v => {} },
    new HelpOption(),
    _,
    "Arguments:",
    { "<files>*", "Input files", new List<string>() },
    _,
    "Available commands:",
    new Command("build") { (ctx, _) => ValueTask.FromResult(0) },
    _,
    "Run 'myexe <command> --help' for more information.",
    (ctx, _) => ValueTask.FromResult(0)
};
```

--------------------------------

### C# example: Define command-line options and commands with XenoAtom.CommandLine

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/readme.md

This snippet shows how to build a command-line application using XenoAtom.CommandLine. It defines options for name, age, and key-value pairs, a 'commit' command with message and file arguments, and default actions. Note that the command graph is not concurrent-safe for multiple invocations.

```csharp
using System;
using XenoAtom.CommandLine;

const string _ = "";
string? name = null;
int age = 0;
List<(string, string?)> keyValues = new List<(string, string?)>();
List<string> messages = new List<string>();
List<string> commitFiles = new List<string>();

var commandApp = new CommandApp("myexe")
{
    new CommandUsage(),
    _,
    {"D:", "Defines a {0:name} and optional {1:value}", (key, value) =>
    {
        if (key is null) throw new CommandOptionException("The key is mandatory for a define", "D");
        keyValues.Add((key, value));
    }},
    {"n|name=", "Your {NAME}", v => name = v},
    {"a|age=", "Your {AGE}", (int v) => age = v},
    new HelpOption(),
    _,
    "Available commands:",
    new Command("commit")
    {
        _,
        "Options:",
        {"m|message=", "Add a {MESSAGE} to this commit", messages},
        new HelpOption(),
        _,
        "Arguments:",
        { "<files>*", "Files to commit", commitFiles },

        // Action for the commit command
        (ctx, _) =>
        {
            ctx.Out.WriteLine($"Committing with name={name}, age={age}");
            foreach (var message in messages)
            {
                ctx.Out.WriteLine($"Commit message: {message}");
            }
            foreach (var file in commitFiles)
            {
                ctx.Out.WriteLine($"Commit file: {file}");
            }
            return ValueTask.FromResult(0);
        }
    },
    // Default action if no command is specified
    (ctx, _) =>
    {
        ctx.Out.WriteLine($"Hello {name}! You are {age} years old.");
        if (keyValues.Count > 0)
        {
            foreach (var keyValue in keyValues)
            {
                ctx.Out.WriteLine($"Define: {keyValue.Item1} => {keyValue.Item2}");
            }
        }

        return ValueTask.FromResult(0);
    }
};

await commandApp.RunAsync(args);
```

--------------------------------

### Markup Output Test Setup with InMemoryTerminalBackend

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Initializes an InMemoryTerminalBackend to capture output deterministically. Configures a CommandApp with a TerminalMarkupCommandOutput that disables terminal width usage for consistent output. Runs the app with --help and a fixed width of 80, then retrieves the output text for assertions.

```csharp
var backend = new InMemoryTerminalBackend();
Terminal.Initialize(backend);

var app = new CommandApp("testapp", config: new CommandConfig
{
    OutputFactory = _ => new TerminalMarkupCommandOutput(new TerminalMarkupOutputOptions
    {
        UseTerminalWindowWidth = false,  // use CommandRunConfig.Width for deterministic output
    })
})
{
    new CommandUsage(),
    "Options:",
    { "n|name=", "The {NAME}", v => { } },
    { "v|verbose", "Enable verbose output", v => { } },
    new HelpOption(),
};

await app.RunAsync(["--help"], new CommandRunConfig(Width: 80));

var output = backend.GetOutText();
// Assert output contains expected ANSI-styled text
```

--------------------------------

### Markup Tier — multi --help

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Example output of `multi --help` with ANSI styling applied, showing bold headers, cyan option prototypes, and dim footer.

```text
Usage: multi [options] <command>          ← bold

Options:                                  ← bold
  -D[=NAME:VALUE]            Add a ...   ← prototype in cyan
  -f=FILE                    The input…
  -x                         Extract …
  -c                         Create …
  -t                         List …
  -a, --advanced             Show adv…   ← cyan
  -h, -?, --help             Show thi…   ← cyan
  -v, --version              Show the…

Available commands:                       ← bold
  hello                      This is …   ← name in cyan
  world                      This is …

Run 'multi [command] --help' for …        ← dim
```

--------------------------------

### Custom JSON output renderer implementing ICommandOutput

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Example implementation that outputs JSON for help, errors, unknown tokens, version, and license header. Uses runConfig.Out and runConfig.Error for output.

```csharp
public sealed class JsonOutputRenderer : ICommandOutput
{
    public void WriteHelp(Command command, CommandRunConfig runConfig)
    {
        // Access command.Options, command.Arguments, command.SubCommands
        runConfig.Out.WriteLine("{ \"help\": \"" + command.GetFullCommandPath() + "\" }");
    }

    public void WriteError(Command command, CommandRunConfig runConfig, CommandException exception)
    {
        runConfig.Error.WriteLine("{ \"error\": \"" + exception.Message + "\" }");
    }

    public void WriteUnknownTokens(Command command, CommandRunConfig runConfig, UnknownTokenReport report)
    {
        foreach (var token in report.UnknownTokens)
            runConfig.Error.WriteLine("{ \"unknown\": \"" + token.Token + "\" }");
    }

    public void WriteVersion(Command command, CommandRunConfig runConfig, string version)
        => runConfig.Out.WriteLine("{ \"version\": \"" + version + "\" }");

    public void WriteLicenseHeader(Command command, CommandRunConfig runConfig, string licenseText)
        => runConfig.Out.WriteLine(licenseText);
}
```

--------------------------------

### Parse API example for unit testing

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Shows how to use CommandApp.Parse to run the parsing pipeline without invoking the command action. Option callbacks are invoked, and errors are collected in the result. Useful for testing option binding and constraint checks.

```csharp
string? name = null;
int port = 0;

var app = new CommandApp("myexe")
{
    { "n|name=", "Your {NAME}", v => name = v },
    { "p|port=", "Server {PORT}", (int v) => port = v },
    new HelpOption(),
    (ctx, _) => ValueTask.FromResult(0)
};

var result = app.Parse(["--name", "Alice", "--port", "8080"]);

// result.HasErrors          → false
// result.ResolvedCommandPath → "myexe"
// result.OptionValues["name"][0] → "Alice"
// result.OptionValues["port"][0] → "8080"
// name → "Alice" (option callbacks are invoked)
// port → 8080
```

--------------------------------

### Collection-initializer integration for constraints

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md

Shows how to add constraints to a CommandApp using collection initializer syntax, alongside option definitions. This example declares mutually exclusive constraints for json/xml and quiet/verbose, and a requires constraint for password requiring user.

```csharp
var app = new CommandApp("myexe")
{
    { "j|json", "Output as JSON", v => json = true },
    { "x|xml",  "Output as XML",  v => xml = true },
    { "q|quiet",   "Suppress output", v => quiet = true },
    { "V|verbose", "Verbose output",  v => verbose = true },
    { "u|user=",     "Username", v => user = v },
    { "P|password=", "Password", v => password = v },

    // Constraints
    new MutuallyExclusiveConstraint("json", "xml"),
    new MutuallyExclusiveConstraint("quiet", "verbose"),
    new RequiresConstraint("password", "user"),
};
```

--------------------------------

### CommandOutputHelper.GetOptionValueName(Option, int)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Gets the display name for an option value placeholder from its description. For example, extracts "PORT" from the description "Server {PORT}". This is a static helper method for custom ICommandOutput implementations.

```APIDOC
## CommandOutputHelper.GetOptionValueName(Option, int)

### Description
Gets the display name for an option value placeholder from its description. For example, extracts "PORT" from the description "Server {PORT}".

### Method
GetOptionValueName

### Signature
public static string GetOptionValueName(Option option, int valueIndex = 0)

### Parameters
- **option** (Option) - Required - The option to get the argument name for.
- **valueIndex** (int) - Optional - The value index (0-based, for multi-value options). Default is 0.

### Returns
- **string** - The argument display name (e.g., "PORT", "VALUE").

```

--------------------------------

### Build the website with lunet

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/AGENTS.md

Build the static website. Run from the site folder after changing site/**.

```bash
lunet build
```

--------------------------------

### Build and test the library

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/AGENTS.md

Run from the project root. Builds the solution in Release configuration and runs all tests.

```sh
cd src
dotnet build -c Release
dotnet test -c Release
```

--------------------------------

### Minimal CLI application with CommandApp

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/getting-started.md

Creates a minimal command-line application named 'greet' with an optional name option, built-in help, and an action that prints a greeting. The action runs after options are parsed, and RunAsync parses arguments and invokes the action.

```cs
using XenoAtom.CommandLine;

string? name = null;

var app = new CommandApp("greet")
{
    { "n|name=", "Your {NAME}", v => name = v },
    new HelpOption(),
    (ctx, _) =>
    {
        ctx.Out.WriteLine($"Hello, {name ?? "World"}!");
        return ValueTask.FromResult(0);
    }
};

await app.RunAsync(args);
```

--------------------------------

### Diagnostic source context output example

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Example output when the diagnostic source is not CommandLine, showing the source context prepended to the error.

```text
[bold red]Error[/] [dim](in response file 'args.txt'):[/] invalid value for --port
```

--------------------------------

### Command.ShowHelp(ICommandOutput, CommandRunConfig?)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Shows help using a specific output implementation. This overload routes the license header through output.WriteLicenseHeader(...) (if configured) before calling output.WriteHelp(...).

```APIDOC
## Command.ShowHelp(ICommandOutput, CommandRunConfig?)

### Description
Shows help using a specific output implementation. This overload routes the license header through output.WriteLicenseHeader(...) (if configured) before calling output.WriteHelp(...).

### Method
ShowHelp

### Signature
public void ShowHelp(ICommandOutput output, CommandRunConfig? runConfig = null)

### Parameters
- **output** (ICommandOutput) - Required - The output implementation to write help to.
- **runConfig** (CommandRunConfig?) - Optional - The run configuration. Default is null.

### Returns
- **void** - This method does not return a value.

```

--------------------------------

### WriteError output example

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md

Example output for a missing required option error, showing the error header, diagnostic underline, and help hint.

```text
[bold red]Error:[/] missing required option: --name
[dim]  multi hello --age 25[/]
[red]                       ^^^^^[/]
[dim]Use `multi hello --help` for usage.[/]
```

--------------------------------

### Output of greet --help

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/getting-started.md

Shows the help output generated by the built-in HelpOption, listing the available options and their descriptions.

```text
Usage: greet [options]

  -n, --name=NAME            Your NAME
  -h, -?, --help             Show this message and exit
```

--------------------------------

### Pass values starting with '-' using '--'

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Shows how to pass positional arguments that start with '-' by using the '--' separator, as strict option parsing treats unknown '-' or '--' tokens as errors.

```sh
myexe -- -5 --not-an-option
```

--------------------------------

### Example error message for invalid env var value

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md

Example of the error message thrown when parsing an environment variable value fails. The message includes the option display name and env var name, but not the value.

```text
Invalid value for option `--port` (from environment variable `SERVER_PORT`): The value must be between 1 and 65535.
```

--------------------------------

### Create CommandApp with root command and options

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/commands.md

Creates a CommandApp named 'myexe' with a verbose option, help option, and a root command action. The app is then run with the provided arguments. If the name is omitted, it defaults to the current executable name.

```csharp
var app = new CommandApp("myexe")
{
    { "v|verbose", "Enable verbose output", v => {} },
    new HelpOption(),
    (ctx, _) =>
    {
        ctx.Out.WriteLine("Root command executed");
        return ValueTask.FromResult(0);
    }
};

await app.RunAsync(args);
```

--------------------------------

### Mutually Exclusive Error Output

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/validation.md

Example error output when the user passes both --json and --xml.

```text
myexe: Options `--json` and `--xml` cannot be used together.
Use `myexe --help` for usage.
```

--------------------------------

### ICommandOutput.WriteHelp

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Renders the help/usage for the specified command. Implement this method to provide custom rendering of help text.

```APIDOC
## ICommandOutput.WriteHelp

### Description
Renders the help/usage for the specified command. Use the command's Options, Arguments, SubCommands, and Nodes properties to access the structured content.

### Method
WriteHelp

### Signature
void WriteHelp(Command command, CommandRunConfig runConfig)

### Parameters
- **command** (Command) - Required - The command whose help should be displayed.
- **runConfig** (CommandRunConfig) - Required - The run configuration providing output streams and layout hints.

### Remarks
Implement this interface to provide custom rendering (e.g., colored terminal UI, structured formats, or machine-readable output).
```

--------------------------------

### Error messages for constraint violations

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md

Example error messages produced when constraints are violated. These messages are passed through CommandConfig.Localizer.

```text
Options `--json` and `--xml` cannot be used together.
Option `--password` requires `--user` to also be specified.
```

--------------------------------

### HTML for project banner

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/banner.md

The banner markup with project name, description, feature pills, install command, and links.

```html
<div class="banner-root">
  <div class="banner-canvas" role="img" aria-label="{{site.project_name}} branding banner">
    <div class="banner-inner">
      <div class="banner-card">
        <div class="banner-top">
          <img class="banner-logo" src="{{site.basepath}}{{site.project_logo_path}}" alt="{{site.project_name}} logo" width="96" height="96">
          <div>
            <h1 class="banner-title"><span class="c64-text">{{site.project_name}}</span></h1>
            <p class="banner-subtitle">{{site.description}}</p>
          </div>
        </div>
        <div class="banner-pill-row" aria-hidden="true">
          <span class="banner-pill"><i class="bi bi-box"></i>Zero dependencies</span>
          <span class="banner-pill"><i class="bi bi-lightning-charge"></i>NativeAOT-friendly</span>
          <span class="banner-pill"><i class="bi bi-terminal"></i>Commands + sub-commands</span>
          <span class="banner-pill"><i class="bi bi-sliders"></i>Powerful option parsing</span>
          <span class="banner-pill"><i class="bi bi-shield-check"></i>Validation + constraints</span>
          <span class="banner-pill"><i class="bi bi-gear-wide-connected"></i>Completions + response files</span>
        </div>
        <div class="banner-code" aria-label="Install command">
          <span>Install:</span>
          <kbd>dotnet add package {{site.project_package_id}}</kbd>
        </div>
        <div class="banner-links">
          <a href="{{site.basepath}}/docs/"><i class="bi bi-book"></i>Docs</a>
          <a href="{{site.github_repo_url}}"><i class="bi bi-github"></i>GitHub</a>
          <a href="https://www.nuget.org/packages/{{site.project_package_id}}/"><i class="bi bi-box-seam"></i>NuGet</a>
        </div>
      </div>
    </div>
  </div>
</div>
```

--------------------------------

### CommandOutputHelper.GetVisibleSubCommands(Command)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Gets the active, visible sub-commands for a command. This is a static helper method for custom ICommandOutput implementations.

```APIDOC
## CommandOutputHelper.GetVisibleSubCommands(Command)

### Description
Gets the active, visible sub-commands for a command.

### Method
GetVisibleSubCommands

### Signature
public static IEnumerable<Command> GetVisibleSubCommands(Command command)

### Parameters
- **command** (Command) - Required - The command to get sub-commands for.

### Returns
- **IEnumerable<Command>** - The active, visible sub-commands.

```

--------------------------------

### Option.EnvironmentVariable Property

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md

Gets or sets the name of the environment variable used as a fallback when this option is not provided on the command line.

```APIDOC
## Option.EnvironmentVariable Property

### Description
Gets or sets the name of the environment variable used as a fallback when this option is not provided on the command line.

### Property Signature
```csharp
public string? EnvironmentVariable { get; set; }
```

### Remarks
Setting this property on any `Option` (including `HelpOption`, `VersionOption`, or custom subclasses) enables the fallback behavior.
```

--------------------------------

### Requires Constraint Error Output

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/validation.md

Example error output when the user passes --password without --user.

```text
myexe: Option `--password` requires `--user` to also be specified.
Use `myexe --help` for usage.
```

--------------------------------

### Testing option parsing with CommandApp

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md

Shows how to set up a CommandApp with options and parse arguments, verifying the parsed values and resolved command path.

```csharp
string? name = null;
int port = 0;

var app = new CommandApp("myexe")
{
    { "n|name=", "Your {NAME}", v => name = v },
    { "p|port=", "Server {PORT}", (int v) => port = v },
    new HelpOption(),
    (ctx, _) => ValueTask.FromResult(0),
};

var result = app.Parse(["--name", "Alice", "--port", "8080"]);

Assert.IsFalse(result.HasErrors);
Assert.AreEqual("Alice", name);
Assert.AreEqual(8080, port);
Assert.AreEqual("myexe", result.ResolvedCommandPath);
```

--------------------------------

### Bundle with value-taking option

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/options.md

Bundles options where one option accepts a value; the value starts from the next character after the option.

```csharp
string? file = null;
var app = new CommandApp("myexe")
{
    { "x", "Extract", v => {} },
    { "f=", "Input {FILE}", v => file = v },
};

await app.RunAsync(["-xfarchive.tar"]); // file == "archive.tar"
```

--------------------------------

### Create a CommandApp with options and help

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/readme.md

Shows the basic usage of XenoAtom.CommandLine: create a CommandApp with an option prototype, a HelpOption, and a command action. The action writes a greeting and returns 0. Run with app.RunAsync(args).

```csharp
var app = new CommandApp("myexe")
{
    { "n|name=", "Your {NAME}", v => name = v },
    new HelpOption(),
    (ctx, _) =>
    {
        ctx.Out.WriteLine($"Hello, {name}!");
        return ValueTask.FromResult(0);
    }
};

await app.RunAsync(args);
```

--------------------------------

### CommandOutputHelper.GetVisibleArgumentSources(Command)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Gets the active, visible argument sources for a command. This is a static helper method for custom ICommandOutput implementations.

```APIDOC
## CommandOutputHelper.GetVisibleArgumentSources(Command)

### Description
Gets the active, visible argument sources for a command.

### Method
GetVisibleArgumentSources

### Signature
public static IEnumerable<ArgumentSource> GetVisibleArgumentSources(Command command)

### Parameters
- **command** (Command) - Required - The command to get argument sources for.

### Returns
- **IEnumerable<ArgumentSource>** - The active, visible argument sources.

```

--------------------------------

### CommandOutputHelper.GetVisibleArguments(Command)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Gets the active, visible positional arguments for a command. This is a static helper method for custom ICommandOutput implementations.

```APIDOC
## CommandOutputHelper.GetVisibleArguments(Command)

### Description
Gets the active, visible positional arguments for a command.

### Method
GetVisibleArguments

### Signature
public static IEnumerable<CommandArgument> GetVisibleArguments(Command command)

### Parameters
- **command** (Command) - Required - The command to get arguments for.

### Returns
- **IEnumerable<CommandArgument>** - The active, visible positional arguments.

```

--------------------------------

### Build the documentation site

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/AGENTS.md

Run from the project root when site/docs changes. Builds the documentation site using lunet.

```sh
cd site
lunet build
```

--------------------------------

### Output of 'myexe --help'

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/readme.md

Shows the help output for the main command, listing options and available commands.

```text
Usage: myexe [options] <command>

  -D[=name:value]            Defines a name and optional value
  -n, --name=NAME            Your NAME
  -a, --age=AGE              Your AGE
  -h, -?, --help             Show this message and exit

Available commands:
  commit
```

--------------------------------

### Define a command app with help text

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Creates a CommandApp with options, a help option, commands, and a default handler. The help output lists options and commands in declaration order.

```csharp
var app = new CommandApp("myexe")
{
    "Options:",
    { "v|verbose", "Enable verbose output", v => {} },
    { "n|name=", "Your {NAME}", v => {} },
    new HelpOption(),
    "",
    "Available commands:",
    new Command("build", "Build the project") { (ctx, _) => ValueTask.FromResult(0) },
    new Command("test", "Run tests") { (ctx, _) => ValueTask.FromResult(0) },
    (ctx, _) => ValueTask.FromResult(0)
};
```

--------------------------------

### Command.ShowHelp overload with ICommandOutput

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Overload for showing help with a specific output implementation, enabling scenarios like --help-json or hosting in a UI. Routes the license header through output.WriteLicenseHeader(...) if configured before calling output.WriteHelp(...).

```csharp
public void ShowHelp(ICommandOutput output, CommandRunConfig? runConfig = null);
```

--------------------------------

### CommandOutputHelper.GetVisibleOptions(Command)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Gets the active, visible options for a command (deduplicated across aliases). This is a static helper method for custom ICommandOutput implementations.

```APIDOC
## CommandOutputHelper.GetVisibleOptions(Command)

### Description
Gets the active, visible options for a command (deduplicated across aliases).

### Method
GetVisibleOptions

### Signature
public static IEnumerable<Option> GetVisibleOptions(Command command)

### Parameters
- **command** (Command) - Required - The command to get options for.

### Returns
- **IEnumerable<Option>** - The active, visible options.

```

--------------------------------

### Command with inline visual (desired syntax)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/visual-as-command-specs.md

Illustrates the proposed syntax for embedding a Terminal.UI Visual directly in a command definition, using TextFiglet as an example.

```csharp
new Command("tool")
{
    new TextFiglet("HelloWorld").Style(...),
    "Options:",
    ...
}
```

--------------------------------

### Create CommandRunConfig and run app

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Configures runtime behavior for a specific invocation. Sets Width, OptionWidth, Out, Error, and ShowLicenseOnRun. Width defaults to 80, OptionWidth to 29, Out to Console.Out, Error to Console.Error, and ShowLicenseOnRun to true.

```csharp
var runConfig = new CommandRunConfig(Width: 120, OptionWidth: 32)
{
    Out = Console.Out,
    Error = Console.Error,
    ShowLicenseOnRun = true,
};

await app.RunAsync(args, runConfig);
```

--------------------------------

### Custom Argument Source (EnvironmentSource)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Example of a custom ArgumentSource that reads arguments from environment variables. It uses the @env prefix and splits the value on spaces.

```csharp
public class EnvironmentSource : ArgumentSource
{
    public override string Description => "Read arguments from environment";
    public override string[] GetNames() => ["@env"];
    public override bool TryGetArguments(string value, out IEnumerable<string>? arguments)
    {
        if (value.StartsWith("@env:"))
        {
            var envValue = Environment.GetEnvironmentVariable(value[5..]);
            arguments = envValue?.Split(' ') ?? [];
            return true;
        }
        arguments = null;
        return false;
    }
}
```

--------------------------------

### Install XenoAtom.CommandLine.Terminal package

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/help-output.md

Adds the optional XenoAtom.CommandLine.Terminal package for rich colored and visual help output. The package targets net10.0 and depends on XenoAtom.Terminal.UI.

```sh
dotnet add package XenoAtom.CommandLine.Terminal
```

--------------------------------

### Stop parsing with '--'

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/arguments.md

Uses '--' to stop option parsing, so tokens after it are treated as positional arguments. Useful when argument values start with '-'.

```sh
myexe -- --not-an-option -x /mnt/home
```

--------------------------------

### Using the Default OutputFactory (No Change Required)

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md

Shows the existing code that continues to work because OutputFactory defaults to null, using the built-in renderer. This is the baseline usage of CommandApp with options and a run callback.

```csharp
// Existing code continues to work — OutputFactory defaults to null (built-in renderer).
var app = new CommandApp("myexe")
{
    new HelpOption(),
    { "n|name=", "Your {NAME}", v => name = v },
    (ctx, args) => ValueTask.FromResult(0),
};
await app.RunAsync(args);
```

--------------------------------

### Publish with NativeAOT

Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/advanced.md

Command to publish the application as a NativeAOT binary for win-x64. Requires the PublishAot property set to true.

```sh
dotnet publish -c Release -r win-x64 /p:PublishAot=true
```
Tokens:
Raw