### 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] -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] * Options: -m, --message=MESSAGE Commit MESSAGE -h, -?, --help Show this message and exit Arguments: * 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] * Options: -n, --name=VALUE This is a name -a, --age=AGE Sets the AGE -h, -?, --help Show this message and exit Arguments: * 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; /// /// Extension methods for building Terminal.UI visuals from command-line objects. /// public static class CommandTerminalExtensions { /// /// Builds a help from the specified command. /// /// The command whose help to visualize. /// Optional visual builder options. /// A that can be written with Terminal.Write(visual) /// or embedded in a fullscreen app. /// /// /// // Inline usage: /// Terminal.Write(command.ToHelpVisual()); /// /// // Fullscreen usage: /// Terminal.Run(new ScrollViewer(command.ToHelpVisual()), ...); /// /// 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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.[/] ``` -------------------------------- ### 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 */); ``` -------------------------------- ### 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 ``` -------------------------------- ### 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:", { "*", "Input files", new List() }, _, "Available commands:", new Command("build") { (ctx, _) => ValueTask.FromResult(0) }, _, "Run 'myexe --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 messages = new List(); List commitFiles = new List(); 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 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] ← 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); } ``` -------------------------------- ### 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 ``` -------------------------------- ### 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"). ``` -------------------------------- ### Manual environment variable fallback example Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md Shows the current manual approach to reading an environment variable as a fallback for an option. The environment variable name is not visible in help output or shell completions. ```csharp string? token = Environment.GetEnvironmentVariable("MY_TOKEN"); var app = new CommandApp("myexe") { { "t|token=", "API {TOKEN}", v => token = v }, // ... }; ``` -------------------------------- ### 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 ``` -------------------------------- ### Extended Add overloads usage examples Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/misc-features-specs.md Shows how to use the new Add overloads with an envVar parameter. The envVar is required to preserve source compatibility. For argument prototypes, specifying envVar is invalid and throws ArgumentException. ```csharp // Shorthand (string action) { "t|token=", "API {TOKEN}", v => token = v, "MY_TOKEN" } // Typed value { "p|port=", "Server {PORT}", (int v) => port = v, "SERVER_PORT" } // Collection binding (opt-in splitting) { "i|include=", "Include {PATH}", includes, "MY_INCLUDES", Path.PathSeparator } ``` -------------------------------- ### 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 ``` -------------------------------- ### CommandOutputHelper.GetDescriptionText(string?) Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/pluggable-output-specs.md Gets only the description text from an option description, stripping argument-name placeholders (e.g., "{PORT}" becomes "PORT" inline). This is a static helper method for custom ICommandOutput implementations. ```APIDOC ## CommandOutputHelper.GetDescriptionText(string?) ### Description Gets only the description text from an option description, stripping argument-name placeholders (e.g., "{PORT}" becomes "PORT" inline). ### Method GetDescriptionText ### Signature public static string GetDescriptionText(string? description) ### Parameters - **description** (string?) - Required - The description to process. ### Returns - **string** - The description text without placeholders. ``` -------------------------------- ### Visual Tier — multi --help Source: https://github.com/xenoatom/xenoatom.commandline/blob/main/site/docs/specs/terminal-visual-specs.md Example output of `multi --help` rendered using `Terminal.Write(Visual)` with borderless `Table` controls. Column widths are auto-calculated by the `Table` control rather than using a fixed `OptionWidth`. ```text Usage: multi [options] ← Markup (`UsageStyle`) Options: ← Markup (`SectionHeaderStyle`) -D[=NAME:VALUE] Add a marco NAME… ← Table row, prototype styled (accent) -f=FILE The input FILE ← auto-aligned columns -x Extract the file -c Create the file -t List the file -a, --advanced Show advanced options -h, -?, --help Show this message… -v, --version Show the version… Available commands: ← Markup (`SectionHeaderStyle`) hello This is a hello… ← Table row, name styled (accent) world This is a world… Run 'multi [command] --help' for … ← Markup, dim ``` -------------------------------- ### 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); ``` -------------------------------- ### 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. ``` -------------------------------- ### 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. ``` -------------------------------- ### 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 GetVisibleSubCommands(Command command) ### Parameters - **command** (Command) - Required - The command to get sub-commands for. ### Returns - **IEnumerable** - 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 GetVisibleArgumentSources(Command command) ### Parameters - **command** (Command) - Required - The command to get argument sources for. ### Returns - **IEnumerable** - 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 GetVisibleArguments(Command command) ### Parameters - **command** (Command) - Required - The command to get arguments for. ### Returns - **IEnumerable** - 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] -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