Kiwify.Kiwi.CLI.Declarative 1.0.0

Kiwify.Kiwi.CLI.Declarative

Attribute-based command definition for Kiwify.Kiwi.CLI. Decorate plain C# classes with attributes and let CommandLoader build the Command<T> objects automatically - no manual AddOption or validation-rule wiring required.

Target: netstandard2.1 Dependencies: Kiwify.Kiwi.CLI

Attributes

Command definition

Validation

Quick start

[CliCommand("deploy", Description = "Deploy to an environment.")]
[RequiredWhen("Environment", "production", RequiredFields = ["BackupPath"])]
[CustomValidation(nameof(ValidateReplicas))]
public class DeployCommand
{
    [CliOption("--environment", "-e", Description = "Target environment", IsRequired = true)]
    public string Environment { get; set; } = "";

    [CliOption("--replicas", "-r", Description = "Instance count", DefaultValue = 1)]
    public int Replicas { get; set; }

    [CliOption("--backup-path", Description = "Snapshot path (required in production)")]
    public string? BackupPath { get; set; }

    [CliHandler]
    public void Execute(IOutput output)
    {
        output.WriteInfo($"Deploying to {Environment} with {Replicas} replica(s).");
    }

    public static bool ValidateReplicas(DeployCommand cmd) =>
        cmd.Replicas >= 1 && cmd.Replicas <= 10;
}

Registering commands

using Kiwify.Kiwi.CLI.Declarative.Extensions;

var app = new CommandLineApplication("mytool", "1.0.0");

// Option 1: auto-discover every [CliCommand] in the calling assembly
app.LoadCommandsFromAssembly();

// Option 2: load from a specific assembly
app.LoadCommandsFromAssembly(typeof(DeployCommand).Assembly);

// Option 3: load a single known type
app.LoadCommandFrom<DeployCommand>();

// Option 4: mix with manually-added fluent commands
app.AddCommand(myFluentCommand);
app.LoadCommandsFromAssembly();   // adds the declarative ones on top

app.Execute(args);

Handler signatures

CommandLoader recognises four handler signatures - static or instance, with or without IOutput:

// Static - command object is passed as the first parameter
public static void Execute(MyCommand cmd) { ... }
public static void Execute(MyCommand cmd, IOutput output) { ... }

// Instance - access properties via `this`; preferred in declarative mode
public void Execute() { ... }
public void Execute(IOutput output) { ... }

A method named Execute is discovered automatically. Use [CliHandler] to designate a differently-named method. Instance handlers are the recommended style: they read naturally and work seamlessly with dependency-injected command objects (the DI container constructs the command, so services are already available as fields).

Enum options

Declare a property with an enum type - CommandLoader maps it to EnumOption<TEnum> automatically, constraining accepted input to the enum member names:

[CliOption("--scope", "-s", DefaultValue = "local")]
public ConfigScope Scope { get; set; }

public enum ConfigScope { Local, Project, Global }

RequiredWhen with operators

Use ComparisonOperator for non-equality conditions on numeric or boolean fields:

using Kiwify.Kiwi.CLI.Declarative.Attributes.Enums;

[RequiredWhen(nameof(RetryCount), 4,
    Operator = ComparisonOperator.GreaterThan,
    RequiredFields = [nameof(BackupPath)])]
public class CopyCommand
{
    public int RetryCount { get; set; }
    public string? BackupPath { get; set; }
    ...
}

Available operators: Equals, NotEquals, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual.

Per-command case sensitivity

Set CaseSensitiveFlags = true on [CliCommand] to make flag matching case-sensitive for that command, independent of the application-level setting:

[CliCommand("diagnose", CaseSensitiveFlags = true)]
public class DiagnoseCommand
{
    [CliOption("--host", "-H")]    // -H is distinct from -h (help)
    public string Host { get; set; } = "";

    [CliOption("--verbose", "-V")] // -V is distinct from -v (version)
    public bool Verbose { get; set; }

    public void Execute(IOutput output)
    {
        output.WriteInfo($"Checking {Host}...");
    }
}

Either the app-level caseSensitiveFlags constructor parameter or the attribute-level CaseSensitiveFlags property opts the command in - whichever is true wins:

// app-level flag off, but DiagnoseCommand is still case-sensitive via its attribute
var app = new CommandLineApplication("mytool", "1.0.0");
app.LoadCommandFrom<DiagnoseCommand>();
app.Execute(args);

RequiredOnlyOneFieldGroup - same GroupId pattern

Multiple [RequiredOnlyOneFieldGroup] attributes sharing the same GroupId define the option groups within one constraint. Exactly one group must be fully satisfied:

// Exactly one of { Username+Password } or { CredentialFile } must be provided.
[RequiredOnlyOneFieldGroup(nameof(Username), nameof(Password), GroupId = 1)]
[RequiredOnlyOneFieldGroup(nameof(CredentialFile),             GroupId = 1)]
public class LoginCommand { ... }

Attributes with different GroupId values create independent constraints.