Sorcha CLI Skill

The Sorcha CLI (sorcha) is a .NET 10 global tool for managing the Sorcha distributed ledger platform. It uses System.CommandLine 2.0.2 for command parsing, Refit for HTTP API clients, and Spectre.Console for rich terminal output.

Project Location

src/Apps/Sorcha.Cli/
├── Commands/           # Command implementations
├── Infrastructure/     # Helpers (ConsoleHelper, ExitCodes, HttpClientFactory)
├── Models/             # Request/Response DTOs for APIs
├── Services/           # Refit interfaces and service contracts
└── Program.cs          # Entry point and command registration

Quick Reference

Creating a New Command

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Sorcha Contributors

using System.CommandLine;
using System.CommandLine.Parsing;
using System.Net;
using System.Text.Json;
using Refit;
using Sorcha.Cli.Infrastructure;
using Sorcha.Cli.Services;

namespace Sorcha.Cli.Commands;

public class MyCommand : Command
{
    private readonly Option<string> _idOption;
    private readonly Option<bool> _verboseOption;

    public MyCommand(
        HttpClientFactory clientFactory,
        IAuthenticationService authService,
        IConfigurationService configService)
        : base("mycommand", "Description of command")
    {
        // IMPORTANT: Option constructor takes (name, description) NOT (alias1, alias2)
        _idOption = new Option<string>("--id", "The resource ID")
        {
            Required = true
        };

        _verboseOption = new Option<bool>("--verbose", "Enable verbose output")
        {
            Required = false
        };

        // Add options to command
        Options.Add(_idOption);
        Options.Add(_verboseOption);

        // Set the action handler
        this.SetAction(async (ParseResult parseResult, CancellationToken ct) =>
        {
            var id = parseResult.GetValue(_idOption)!;
            var verbose = parseResult.GetValue(_verboseOption);

            // Implementation here
            return ExitCodes.Success;
        });
    }
}

System.CommandLine 2.0.2 Key Points

Pattern	Correct	Wrong
Option constructor	`new Option<string>("--id", "Description")`	`new Option<string>("--id", "-i")`
Add short alias	`option.Aliases.Add("-i")`	Second constructor param
Option name property	Returns `"--id"` (with dashes)	Does NOT return `"id"`
Get option value	`parseResult.GetValue(_option)`	`parseResult.GetValueForOption()`
Set action	`this.SetAction(async (pr, ct) => {...})`	Override Execute
Test find option	`o.Name == "--id"`	`o.Aliases.Contains("--id")`

Testing Note: The Aliases collection does NOT include the option name. Use o.Name == "--id" to find options in tests.

Adding Short Aliases

_idOption = new Option<string>("--id", "The resource ID") { Required = true };
_idOption.Aliases.Add("-i");  // Add short alias separately
Options.Add(_idOption);

Parent Command with Subcommands

public class ParentCommand : Command
{
    public ParentCommand(
        HttpClientFactory clientFactory,
        IAuthenticationService authService,
        IConfigurationService configService)
        : base("parent", "Parent command description")
    {
        Subcommands.Add(new ChildListCommand(clientFactory, authService, configService));
        Subcommands.Add(new ChildGetCommand(clientFactory, authService, configService));
        Subcommands.Add(new ChildCreateCommand(clientFactory, authService, configService));
    }
}

Registering Commands in Program.cs

// Program.cs
rootCommand.Subcommands.Add(new MyCommand(clientFactory, authService, configService));

Refit Service Clients

Interface Definition

// Services/IMyServiceClient.cs
using Refit;

public interface IMyServiceClient
{
    [Get("/api/resources")]
    Task<List<Resource>> ListAsync([Header("Authorization")] string authorization);

    [Get("/api/resources/{id}")]
    Task<Resource> GetAsync(string id, [Header("Authorization")] string authorization);

    [Post("/api/resources")]
    Task<Resource> CreateAsync([Body] CreateRequest request, [Header("Authorization")] string authorization);

    [Put("/api/resources/{id}")]
    Task<Resource> UpdateAsync(string id, [Body] UpdateRequest request, [Header("Authorization")] string authorization);

    [Delete("/api/resources/{id}")]
    Task DeleteAsync(string id, [Header("Authorization")] string authorization);

    // Pagination with query parameters
    [Get("/api/resources")]
    Task<List<Resource>> ListAsync(
        [Query] int? page,
        [Query] int? pageSize,
        [Header("Authorization")] string authorization);

    // OData queries
    [Get("/odata/{resource}")]
    Task<HttpResponseMessage> QueryODataAsync(
        string resource,
        [Query("$filter")] string? filter,
        [Query("$orderby")] string? orderby,
        [Query("$top")] int? top,
        [Query("$skip")] int? skip,
        [Header("Authorization")] string authorization);
}

Using Refit Client in Commands

// Get client from factory
var client = await clientFactory.CreateMyServiceClientAsync(profileName);

// Get auth token
var token = await authService.GetAccessTokenAsync(profileName);
if (string.IsNullOrEmpty(token))
{
    ConsoleHelper.WriteError("You must be authenticated.");
    return ExitCodes.AuthenticationError;
}

// Call API with Bearer token
var result = await client.GetAsync(id, $"Bearer {token}");

Error Handling Pattern

try
{
    var result = await client.GetAsync(id, $"Bearer {token}");
    // Success handling
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    ConsoleHelper.WriteError($"Resource '{id}' not found.");
    return ExitCodes.NotFound;
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.Unauthorized)
{
    ConsoleHelper.WriteError("Authentication failed. Your access token may have expired.");
    ConsoleHelper.WriteInfo("Run 'sorcha auth login' to re-authenticate.");
    return ExitCodes.AuthenticationError;
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.Forbidden)
{
    ConsoleHelper.WriteError("You do not have permission to access this resource.");
    return ExitCodes.AuthorizationError;
}
catch (ApiException ex)
{
    ConsoleHelper.WriteError($"API Error: {ex.Message}");
    if (ex.Content != null)
    {
        ConsoleHelper.WriteError($"Details: {ex.Content}");
    }
    return ExitCodes.GeneralError;
}
catch (Exception ex)
{
    ConsoleHelper.WriteError($"Failed: {ex.Message}");
    return ExitCodes.GeneralError;
}

Console Output Helpers

// Success message (green)
ConsoleHelper.WriteSuccess("Operation completed successfully!");

// Error message (red)
ConsoleHelper.WriteError("Something went wrong.");

// Warning message (yellow)
ConsoleHelper.WriteWarning("This action cannot be undone.");

// Info message (cyan)
ConsoleHelper.WriteInfo("Use 'sorcha help' for more information.");

Exit Codes

public static class ExitCodes
{
    public const int Success = 0;
    public const int GeneralError = 1;
    public const int AuthenticationError = 2;
    public const int AuthorizationError = 3;
    public const int NotFound = 4;
    public const int ValidationError = 5;
}

JSON Output Support

// Check output format option
var outputFormat = parseResult.GetValue(BaseCommand.OutputOption) ?? "table";
if (outputFormat.Equals("json", StringComparison.OrdinalIgnoreCase))
{
    Console.WriteLine(JsonSerializer.Serialize(result, new JsonSerializerOptions { WriteIndented = true }));
    return ExitCodes.Success;
}

// Otherwise display as table
Console.WriteLine($"{"ID",-36} {"Name",-30} {"Status",-10}");
Console.WriteLine(new string('-', 80));
foreach (var item in results)
{
    Console.WriteLine($"{item.Id,-36} {item.Name,-30} {item.Status,-10}");
}

Related Skills

dotnet - .NET 10 / C# 13 patterns
xunit - Unit testing with xUnit
fluent-assertions - FluentAssertions patterns
moq - Mocking with Moq

Dependencies

Package	Version	Purpose
System.CommandLine	2.0.2	CLI framework
Refit	9.0.2	HTTP client
Refit.HttpClientFactory	9.0.2	DI integration
Spectre.Console	0.54.0	Rich console output
System.IdentityModel.Tokens.Jwt	8.3.0	JWT token handling

Tool Version Management

The Sorcha CLI can be installed as a .NET global tool or run from local build. When working on the CLI, check for version mismatches.

Check for Global Tool Installation

# Check if sorcha is installed as a global tool
dotnet tool list --global | grep -i sorcha

# Find where the current 'sorcha' command is located
which sorcha  # Linux/macOS
where sorcha  # Windows

Uninstall Global Tool (for local development)

If a global tool is installed, it may conflict with local development builds:

# Uninstall global tool to use local build
dotnet tool uninstall --global sorcha.cli

Local Build Paths

After building with dotnet build src/Apps/Sorcha.Cli, the executable is at:

Release: src/Apps/Sorcha.Cli/bin/Release/net10.0/Sorcha.Cli.exe
Debug: src/Apps/Sorcha.Cli/bin/Debug/net10.0/Sorcha.Cli.exe

Walkthrough Scripts

When writing walkthrough scripts that use the CLI, prefer finding the local build:

# PowerShell pattern for finding CLI
$RepoRoot = (Get-Item $PSScriptRoot).Parent.Parent.FullName
$LocalCliPath = Join-Path $RepoRoot "src/Apps/Sorcha.Cli/bin/Release/net10.0/Sorcha.Cli.exe"
$DebugCliPath = Join-Path $RepoRoot "src/Apps/Sorcha.Cli/bin/Debug/net10.0/Sorcha.Cli.exe"

if (Test-Path $LocalCliPath) {
    $SorchaCliPath = $LocalCliPath
} elseif (Test-Path $DebugCliPath) {
    $SorchaCliPath = $DebugCliPath
} else {
    $SorchaCliPath = "sorcha"  # Fall back to global tool
}

Version Mismatch Symptoms

If you see unexpected command options or missing features:

Check if global tool version differs from source code
Rebuild with dotnet build src/Apps/Sorcha.Cli -c Release
Verify using sorcha --version vs ./Sorcha.Cli.exe --version

Documentation Resources

Fetch latest System.CommandLine documentation with Context7.

Library ID: /dotnet/command-line-api

Recommended Queries:

"Option constructor aliases System.CommandLine 2.0"
"SetAction handler pattern"
"ParseResult GetValue"

sorcha-cli