sorcha-cli_skill

Overview

This skill builds and maintains the Sorcha CLI, a .NET 10 global tool that uses System.CommandLine 2.0.2, Refit HTTP clients, and Spectre.Console for rich terminal output. It provides patterns and examples for creating commands, wiring Refit service clients, structured error handling, and producing JSON or table output. The content focuses on practical, testable implementations and developer workflows for local development and tool version management.

How this skill works

The skill shows how to define commands and options with System.CommandLine 2.0.2, register subcommands, and set async handlers using the SetAction pattern. It describes creating Refit interfaces for REST and OData endpoints, obtaining bearer tokens via an authentication service, and calling APIs with explicit error handling for common HTTP responses. ConsoleHelper wrappers and Spectre.Console patterns are used to standardize success, error, warning, and info output.

When to use it

• When adding a new CLI command with required options and short aliases.
• When implementing Refit service clients for REST or OData endpoints.
• When writing unit tests for command parsing and option discovery.
• When handling API errors and mapping them to exit codes.
• When producing machine-readable JSON output or human-readable tables.
• When debugging version mismatches between a global tool and local build.

Best practices

• Declare options with the full name in the constructor (e.g., "--id") and add short aliases via option.Aliases.Add("-i").
• Use this.SetAction(async (ParseResult pr, CancellationToken ct) => { ... }) instead of overriding Execute.
• Find options in tests using o.Name == "--id" because Aliases does not include the name.
• Obtain an auth token before API calls and return clear exit codes for NotFound, Unauthorized, and Forbidden.
• Support json output via a common OutputOption and fall back to table rendering for human users.
• Uninstall a conflicting global tool when running or testing a local build to avoid stale behavior.

Example use cases

• Create a parent command that aggregates list/get/create subcommands for a resource.
• Implement a Refit IMyServiceClient with pagination and OData query methods.
• Write a command that prints JSON when --output json is selected and a table otherwise.
• Add unit tests that assert option presence using option.Name comparisons.
• Handle ApiException filters to map HTTP status codes to ConsoleHelper messages and ExitCodes.