Goal
Define the language-neutral behavior that operations, platform, infrastructure, SRE, and development teams can rely on across company CLIs.
Background
base-cli now has strong Python-specific v1 contracts for JSON success/error envelopes, NDJSON, logs, inspection, and command framing. The cross-language work in #241 validates those serialized fixtures with Python and Node, but it does not define or execute a complete CLI behavior contract.
A universal platform must not require Python, Click, or Typer, and it must not duplicate mature parser ecosystems. Go teams already have Cobra/Viper, Rust has clap, Node has oclif, JVM teams have picocli, and .NET has System.CommandLine. The shared value is consistent behavior and evidence across those implementations.
Scope
- Reconcile a proposed
cli-platform/v1 with the already-published base-cli v1 schemas.
- Define normative behavior for identity/version/help, stdout versus stderr, structured output, exit codes and signals, configuration precedence/provenance, non-interactive operation, dry-run/destructive confirmation, redaction, timeouts/cancellation, deprecation, and diagnostics.
- Mark requirements as universal, capability-dependent, or language/runtime-specific.
- Define compatibility and version negotiation.
Acceptance Criteria
- One reviewed contract maps every existing base-cli v1 field and flag to the platform contract without silently changing meaning.
- Conflicts such as
--json versus --output json have an explicit compatibility decision and migration path.
- Normative MUST/SHOULD/MAY language is testable and parser-neutral.
- The contract defines stdout/stderr, exit/signal, automation, destructive-action, redaction, and deprecation invariants.
- A compatibility matrix covers Python Click/Typer, Go Cobra, Rust clap, Node oclif, JVM picocli, and .NET System.CommandLine.
- Contract ownership, SemVer/versioning, exception approval, and deprecation governance are documented.
- At least two real CLI owners review the contract before it is frozen.
Validation
Review representative CLI transcripts from at least Python and one non-Python implementation; ensure each normative statement can become a black-box conformance assertion.
Non-Goals
- Do not standardize one parser library or one implementation language.
- Do not port base-cli wholesale to every language.
- Do not overwrite the published base-cli v1 JSON contract in place.
Dependencies
Project Fields
- Status: Backlog
- Priority: P1
- Area: Product
- Initiative: v1.0 Readiness
- Size: L
Ownership
Goal
Define the language-neutral behavior that operations, platform, infrastructure, SRE, and development teams can rely on across company CLIs.
Background
base-cli now has strong Python-specific v1 contracts for JSON success/error envelopes, NDJSON, logs, inspection, and command framing. The cross-language work in #241 validates those serialized fixtures with Python and Node, but it does not define or execute a complete CLI behavior contract.
A universal platform must not require Python, Click, or Typer, and it must not duplicate mature parser ecosystems. Go teams already have Cobra/Viper, Rust has clap, Node has oclif, JVM teams have picocli, and .NET has System.CommandLine. The shared value is consistent behavior and evidence across those implementations.
Scope
cli-platform/v1with the already-published base-cli v1 schemas.Acceptance Criteria
--jsonversus--output jsonhave an explicit compatibility decision and migration path.Validation
Review representative CLI transcripts from at least Python and one non-Python implementation; ensure each normative statement can become a black-box conformance assertion.
Non-Goals
Dependencies
Project Fields
Ownership