Oakton

If you want your IDescribedSystemPart to have enhanced, visually rich formatting in the console (e.g., using Spectre.Console tables), implement the IWriteToConsole interface in addition to IDescribedSystemPart.

• Write(TextWriter writer) will still be used when exporting to a file (Markdown).
• WriteToConsole() will be used when the output is directed to the terminal.

public class ReferencedAssemblies : IDescribedSystemPart, IWriteToConsole
{
    public string Title { get; } = "Referenced Assemblies";

    // Used for file export (Markdown)
    public Task Write(TextWriter writer)
    {
        var referenced = Assembly.GetEntryAssembly().GetReferencedAssemblies();
        foreach (var assemblyName in referenced) writer.WriteLine("* " + assemblyName);
        return Task.CompletedTask;
    }

    // Used for console output (Enhanced formatting)
    public Task WriteToConsole()
    {
        var table = new Table();
        table.AddColumn("Assembly Name");
        table.AddColumn("Version");

        var referenced = Assembly.GetEntryAssembly().GetReferencedAssemblies();
        foreach (var assemblyName in referenced) table.AddRow(assemblyName.Name, assemblyName.Version.ToString());

        AnsiConsole.Write(table);
        return Task.CompletedTask;
    }
}

An Oakton command consists of two distinct parts:

1. An Input Class: A concrete class that holds all the argument and flag data inputs.
2. A Command Class: A concrete class that inherits from either OaktonCommand<T> or OaktonAsyncCommand<T>, where T is the input class defined in step 1.

Key characteristics of a command class:

• The entry point is the Execute() method.
• The Execute() method returns a bool indicating success or failure. This return value is used by the OS to signal command completion status, which is critical for automated build pipelines.
• The [Description] attribute provides help text and is optional.
• It is legal to reuse the same input class across multiple different commands.

[Description("Print somebody's name")]
public class NameCommand : OaktonCommand<NameInput>
{
    public NameCommand()
    {
        Usage("Default Color").Arguments(x => x.Name);
    }

    public override bool Execute(NameInput input)
    {
        // Command logic here
        return true;
    }
}

An Argument is any public field or settable property on your input class that is not suffixed with Flag and is not marked with the [IgnoreOnCommandLine] attribute.

Arguments are positional values that appear in the command line before any flags.

Key rules:

• Settable properties and public fields are valid.
• Read-only properties are ignored.
• Use [IgnoreOnCommandLine] to prevent a field/property from being captured from the command line.
• Properties suffixed with Flag are treated as Flags, not arguments.

public class NameInput
{
    // Argument (settable property)
    public string First { get; set; }
    
    // Argument (public field)
    public string Last;

    // Ignored (read-only)
    public string Fullname => $"{First} {Last}";
    
    // Ignored (explicitly)
    [IgnoreOnCommandLine]
    public string Nickname;
    
    // Flag (suffixed with Flag)
    public bool VerboseFlag { get; set; }
}

Extension commands can be implemented by inheriting from OaktonCommand<T> or OaktonAsyncCommand<T>.

If your command needs to access or modify the application's IHostBuilder configuration, you should use NetCoreInput (or a class inheriting from it) as the input type.

NetCoreInput provides access to the IHostBuilder, but it does not automatically build or start the host. This lazy behavior allows you to perform configuration or extensions before calling input.BuildHost() or input.StartHost().

[Description("Simply try to build a web host as a smoke test", Name = "smoke")]
public class SmokeCommand : OaktonCommand<NetCoreInput>
{
    public override bool Execute(NetCoreInput input)
    {
        // input.BuildHost() builds the IWebHost from the configured IHostBuilder
        using (var host = input.BuildHost())
        {
            Console.WriteLine("It's all good");
        }

        return true;
    }
}

Boolean Flags

If a boolean flag appears, the property is set to true. You can combine multiple short flags into a single expression (e.g., -xfd).

Enumerable Flags

Use string[] or IEnumerable<string> to collect multiple values. Oakton knows when the list ends by looking for the next flag.

Key/Value Flags

If a flag is not a boolean, Oakton treats the next string in the command line as the value for that flag.

Example Usage:

# Boolean flags combined
executable command -x -f --force

# Enumerable flags
executable command --files one.txt two.txt --directories dir1 dir2

# Key/Value flags
executable command --create-branch working

public class FileInput
{
    public string[] FilesFlag;
    public string[] DirectoriesFlag;
}

public class CleanInput
{
    public bool ForceFlag { get; set; }
    
    [FlagAlias('d')]
    public bool RemoveUntrackedDirectoriesFlag { get; set; }
    
    [FlagAlias('x')]
    public bool DoNoUseStandardIgnoreRulesFlag { get; set; }
}