Design: first-class support for multi-verb, agent-first product CLIs

[tig]

Problem

Terminal.Gui.Cli already hits an important nerve: one host, typed JSON, POSIX exits, --opencli, agent-guide. The next jump is product-shaped CLIs — not a single greet demo, but tools with a small set of durable verbs that coding agents run reliably.

Agents are good at:

mytool gate
mytool deploy --verify
# fix red, re-run

They are much worse at faithfully executing long prose playbooks (AGENTS.md essays, multi-phase checklists). Products that care about agent-operable workflows keep rediscovering the same needs: discoverable commands, stable contracts, capability-gated verbs, hybrid human steps, and a way to grow the CLI without breaking agents.

The product question for this library:

How do we make it easy to build and maintain multi-verb, agent-first product CLIs on Terminal.Gui.Cli — flexible enough for real products, without every team reinventing command model, discoverability, versioning, and operator UX?

Example verb shapes (illustrative, not a mandate)

Many real tools converge on something like:

Kind of verb	Examples
Health / setup	doctor, auth, init
Project shape	scaffold, new
Quality gate	gate, test, lint
Ship / apply	deploy, publish, apply --verify
Device / env bring-up	flash-first, connect (when relevant)

Concrete products (firmware spines, internal platforms, vertical tools) will name their own verbs. The library question is the pattern, not any one product’s command list.

Open questions

1. Composition and flexibility

• How should a product CLI grow verbs over time without breaking agents that already discovered commands via --opencli?
• Pattern for optional / capability-gated commands (only register flash-first if a transport plugin is present)?
• Plugins / multi-package composition (core + domain packs) vs one fat binary — what’s the intended model?

2. Agent contracts as first-class

• What should every product CLI get for free: schema-versioned JSON, stable exit codes, timeouts, structured errors (what failed + what to try next)?
• What does TG.Cli already guarantee vs what should be standardized next?
• Should agent-guide be generated from the registry + a short product brief so it cannot rot against --opencli?

3. Hybrid human steps (“help the operator”)

Many workflows mix scriptable work with physical or browser steps (plug a device, complete OAuth, click through an installer). Coding agents sit in the middle.

• Patterns for prompts that work in TUI, --json, and non-interactive modes (--initial, --timeout, …)?
• A first-class “blocked on human” result (exit code + structured payload, e.g. need: usb_plugin | browser_auth | confirm) so an agent knows what to ask the human — not a wall of shell?

4. Build / maintain without forking the library

• How do product teams share CI patterns, golden tests for CLI contracts, and upgrade paths when Terminal.Gui.Cli moves?
• Unit of reuse: library only, or also a dotnet new / template for “agent-first product CLI”?
• Versioning: product pins TG.Cli; users/agents pin the product CLI by tag — any recommended practice so tool identity stays honest?

5. In-process vs external process commands

Real product CLIs often orchestrate other tools (test runners, flashers, package managers, cloud CLIs) while still wanting one JSON/exit envelope for agents.

• Is the library in-process View commands only, or are process-backed / plugin commands with the same envelope in scope?
• If in scope: lifecycle, stdout/stderr capture, timeout, mapping to CommandResult, testing story?

6. Diagnostics and continuous improvement

When an agent path is rough, the next agent should not rediscover the same footgun in chat.

• Standard way for a product CLI to emit diagnostic records agents can turn into upstream issues?
• Sample “rehearsal” tests that assert doctor / gate-class verbs stay green under an agent or scripted harness?

Ask

A design discussion or short note on:

1. Recommended architecture for a multi-verb, agent-first product CLI on Terminal.Gui.Cli.
2. Whether external/process-backed commands with the same envelope are in scope.
3. Whether a product CLI template/sample (beyond examples/greet) should exist.
4. Documented anti-patterns (e.g. unbounded subcommand sprawl, mutable “latest” pins in examples, agent-guide that drifts from the registry).

Non-goals for this issue

• Implementing any specific product’s CLI in this repository.
• Replacing domain tools (test runners, device flashers, etc.) — only how a TG.Cli host would orchestrate them cleanly if process-backed commands are supported.

Motivation (optional color)

This came up while designing agent-operable host tooling for edge/firmware workflows, but the same shape shows up for internal platforms, installers, and any product where agents + non-expert operators share one CLI. Happy to refine with other concrete CLIs people are building on TG.