vvka-141/portico

<img src="eng/brand/portico-512.png" alt="" width="88" align="left" hspace="16" vspace="4"

Portico

A contract-first operational command framework for .NET systems.

Compile your operational CLI with the system it operates. Portico turns ordinary C# contracts, application services and referenced assemblies into one composable command surface. A migration, deployment or maintenance command can use the same domain types, dependency graph, cloud clients, policies and lifecycle as the production system — without rebuilding them in a parallel command object graph or a shell script.

Portico is reflection-first by design. Its unit of composition is a .NET contract and assembly, not an AOT-generated standalone executable. Routes bind like ASP.NET endpoints, middleware carries application-wide options and policy, and examples are executable checks of the surface operators actually receive.

using Portico;

public interface IAdminTool
{
    [CliRoute("db migrate")]
    [CliCommandExample("db migrate --connection-string \"Host=db\"", "Apply pending migrations")]
    int Migrate(
        [CliOption("--connection-string|-c", "Postgres connection string", Sensitive = true)]
        string connectionString);
}

public sealed class AdminTool : IAdminTool

public int Migrate(string connectionString) { System.Console.WriteLine("applied 3 migrations."); return 0; } }

public static class Program { public static int Main(string[] args) = CliApplication.Create(cfg = cfg.AddCommands(new AdminTool())).Run(args); }

That is the core shape: a plain C# method, one route attribute, one example.

**That declaration is already three things.** It is the command, it is the `--help` page, and it is a
test — none of them written twice.

Here is the help, which you did not write:

$ admin --help Usage: admin db migrate [options]

Options: --connection-string, -c Postgres connection string

Examples: admin db migrate --connection-string "Host=db" Apply pending migrations

And here is the complete contract test:

public sealed class AdminContractShould { [Fact] public void DispatchEveryExample() = new CliContractValidator<IAdminTool().Validate(); }

`Validate()` runs every `[CliCommandExample]` on the interface through the **real** pipeline against a
`DispatchProxy` — parsing, routing and binding included. Rename `Migrate`, change an option, or let
the example drift from what the CLI accepts, and that one test fails. The example in the help output
above is the same string the test just executed, which is why the help cannot be stale.

## Why Portico

- **One compilation boundary.** The CLI references the same application and platform assemblies as
  the system it operates. Incompatible service, domain-model and package changes meet the compiler
  instead of a production script.
- **A domain-specific operational language.** Derive option and argument attributes, use domain

[ChangeTicket] ChangeTicket ticket rather than restating aliases, conversion and policy on each parameter.

• Commands and policy compose. Team-owned contracts mount beneath route prefixes. A

CliMiddleware is both a bundle of application-wide options and the behavior that enforces them, so controls such as --dry-run, approvals and auditing travel together.