diff --git a/README.md b/README.md index c54e767..3fec970 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,35 @@ # Terminal.Gui.Cli -![Terminal.Gui.Cli Example App](docs/images/hero.gif) +[![NuGet](https://img.shields.io/nuget/vpre/Terminal.Gui.Cli)](https://www.nuget.org/packages/Terminal.Gui.Cli) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -A .NET library that lets [Terminal.Gui](https://github.com/gui-cs/Terminal.Gui) applications expose Views as scriptable CLI commands with typed JSON output, POSIX exit codes, and AI-agent discoverability. +> A .NET library that turns [Terminal.Gui](https://github.com/gui-cs/Terminal.Gui) apps into scriptable CLI tools — with typed JSON output, POSIX exit codes, and built-in AI-agent discoverability. -Ships as a single NuGet package: **[`Terminal.Gui.Cli`](https://www.nuget.org/packages/Terminal.Gui.Cli)**. +![Terminal.Gui.Cli in action](docs/images/hero.gif) -## What it does +## Why -`Terminal.Gui.Cli` provides a hosting layer (`CliHost`) that wires up: +Terminal.Gui gives you rich TUI applications. **Terminal.Gui.Cli** lets those same apps participate in scripts, pipelines, and agentic workflows — no separate CLI layer needed. -- **CLI parsing** — positional command dispatch, typed options, `--initial` pre-fill for input commands. -- **Structured output** — `--json` emits a versioned `JsonEnvelope`; `--cat` renders viewer content headlessly. -- **AI-agent discoverability** — `--opencli` emits machine-readable metadata; `--agent-guide` serves embedded Markdown guidance. -- **Built-in help** — `--help` renders command/option metadata via pluggable `IHelpProvider`. -- **Exit codes** — deterministic POSIX exit codes from `CommandResult` status. +One NuGet package. One `CliHost`. All your views become commands. -## Command model +## Features -| Kind | Interface | Description | -|------|-----------|-------------| -| **Input** | `ICliCommand` | Launches a Terminal.Gui UI, returns a typed result. | -| **Viewer** | `IViewerCommand` | Displays content; supports `--cat` for headless rendering. | - -Commands register explicitly (no reflection scanning) and resolve by case-insensitive alias. +| Capability | How | +|---|---| +| **CLI parsing** | Positional command dispatch, typed options, `--initial` pre-fill | +| **Structured output** | `--json` emits a versioned `JsonEnvelope` | +| **Headless rendering** | `--cat` renders viewer content without a TUI | +| **AI discoverability** | `--opencli` metadata + `agent-guide` embedded Markdown | +| **Built-in help** | `--help` via pluggable `IHelpProvider` | +| **Exit codes** | Deterministic POSIX codes from `CommandResult` | ## Quickstart +```sh +dotnet add package Terminal.Gui.Cli +``` + ```csharp using Terminal.Gui.Cli; @@ -36,29 +39,33 @@ CliHost host = new (options => options.Version = "1.0.0"; }); -host.Registry.Register (new MyCommand ()); +host.Registry.Register (new GreetCommand ()); return await host.RunAsync (args); ``` +Then run it: + ```sh -# Interactive (launches Terminal.Gui) -my-app greet --initial "World" +my-app greet --initial "World" # interactive TUI +my-app greet --initial "World" --json # → {"schemaVersion":1,"status":"ok","value":"Hello, World!"} +my-app info --cat # headless viewer output +my-app --opencli # machine-readable command metadata +my-app agent-guide # embedded agent guidance (Markdown) +``` -# JSON envelope -my-app greet --initial "World" --json +## Command model -# Agent discovery -my-app --opencli -my-app agent-guide +| Kind | Interface | Description | +|------|-----------|-------------| +| **Input** | `ICliCommand` | Launches a Terminal.Gui UI, returns a typed result | +| **Viewer** | `IViewerCommand` | Displays content; supports `--cat` for headless rendering | -# Headless viewer -my-app info --cat -``` +Commands register explicitly (no reflection scanning) and resolve by case-insensitive alias. -## Framework options +## Global options -All commands inherit these options from the host: +Every command inherits these from the host: | Option | Description | |--------|-------------| @@ -66,7 +73,7 @@ All commands inherit these options from the host: | `--version` | Show version | | `--opencli` | Emit OpenCLI metadata JSON | | `--json` | Wrap output in JSON envelope | -| `--initial ` | Pre-fill input value | +| `--initial ` | Pre-fill input value (non-interactive mode) | | `--timeout ` | Cancel after duration (e.g., `30s`, `5m`) | | `--output ` / `-o` | Write output to file | | `--cat` | Headless render (viewer commands only) | @@ -74,35 +81,39 @@ All commands inherit these options from the host: ## Repository layout ``` -specs/ Constitution and library spec src/ Terminal.Gui.Cli library tests/ Unit, integration, and smoke tests -examples/ Example console app +examples/ Example console app (see hero GIF above) +specs/ Constitution and library specification scripts/ Tooling and recording scripts docs/ Images and documentation assets ``` -## Build +## Building from source -Requires .NET 10 SDK. Solution file: `Terminal.Gui.Cli.slnx`. +Requires **.NET 10 SDK**. Solution: `Terminal.Gui.Cli.slnx`. ```sh dotnet restore Terminal.Gui.Cli.slnx dotnet build Terminal.Gui.Cli.slnx -# Tests +# Run all test tiers dotnet run --project tests/Terminal.Gui.Cli.Tests dotnet run --project tests/Terminal.Gui.Cli.IntegrationTests dotnet run --project tests/Terminal.Gui.Cli.SmokeTests -# Example app +# Try the example app dotnet run --project examples/Terminal.Gui.Cli.ExampleApp -- greet --initial "World" --json ``` ## Status -**Alpha** — `0.1.0-develop` pre-release stream on the `develop` branch. +**Alpha** — `0.1.0-develop` pre-release. API surface is stabilizing; breaking changes possible. + +## Contributing + +See [`specs/constitution.md`](specs/constitution.md) for architectural rules and PR requirements. ## License -MIT; see [`LICENSE`](LICENSE). +MIT — see [`LICENSE`](LICENSE). diff --git a/docs/images/hero.gif b/docs/images/hero.gif index da61867..a3670fa 100644 Binary files a/docs/images/hero.gif and b/docs/images/hero.gif differ