Founder Notes/Research
public

OpenCLI In-Depth Research

A complete research note covering the positioning of OpenCLI — an OpenAPI for CLIs — its ecosystem progress, open controversies, and enterprise adoption recommendations

OpenCLI In-Depth Research

Research date: 2026-03-26

One-Line Verdict

OpenCLI is headed in the right direction: it aims to turn a CLI’s commands, arguments, exit codes, and examples into a machine-readable contract, giving documentation generation, automation integration, and MCP bridges a single unified upstream.

But as of 2026-03-26, it is still closer to a draft with clear momentum than to a settled industry standard.

Project Positioning

OpenCLI is driven by spectreconsole/open-cli and positions itself as “OpenAPI for CLIs”:

  • Provide a standard, language-agnostic description format for CLIs
  • Let both humans and machines understand a CLI’s interface without reading its source code
  • Serve as a unified input for documentation, clients, completions, change detection, and MCP / agent bridges

Use cases listed on the official specification site include:

  • Generating documentation
  • Generating clients
  • Generating automation tools and MCP servers
  • Detecting breaking changes in CLI APIs
  • Generating shell completions

Known Progress

  • 2025-07-07: The author published the introductory post Introducing OpenCLI
  • 2025-10-04: The spec changelog was still adding details such as default values, showing the draft is still evolving
  • 2025-10-10: Spectre.Console.Cli 0.52.0 shipped with OpenCLI export capability
  • 2026-02: The community began discussing a steering group, hoping to bring more CLI framework maintainers into governance

Why It’s Worth Watching

  1. It upgrades the CLI from “help text meant only for humans” to “a contract layer that programs can consume”
  2. The connection to MCP is very natural: OpenCLI is a great fit as the upstream description for tool schemas
  3. It’s especially valuable for teams maintaining CLIs in multiple languages: documentation, portals, automation, and regression detection can all be unified
  4. It’s particularly friendly to internal platform teams: turning a pile of in-house CLIs into governable product interfaces

Key Risks Today

1. The discovery mechanism hasn’t converged

The community is still debating how an OpenCLI description should be reliably discovered from a CLI — for example, --help-opencli versus a versioned flag. Until this is resolved, true interoperability between implementations will be hard to achieve.

Related discussion: https://github.com/spectreconsole/open-cli/discussions/46

2. Root command modeling is still under debate

Discussion continues around the relationship between the Document and the root command. This design directly affects the complexity of parsers, generators, and compatibility layers.

Related discussion: https://github.com/spectreconsole/open-cli/discussions/70

3. The type system boundary isn’t fully finalized

There is still clear disagreement over whether to stay as close as possible to JSON Schema or to keep CLI-specific types (e.g. file, directory). This will affect consistency across cross-language toolchains.

4. The ecosystem is sprouting, but not yet fully compatible

Rust already has an opencli crate, the .NET side has OpenCLI → MCP experiments, and the oclif community is discussing a plugin. The positive signals are obvious, but it also means different implementations may now diverge into dialects.

Scenarios Where Adoption Makes Sense

  • Internal platform teams that control both the producer and the consumer
  • R&D infrastructure teams that want to unify CLI documentation, MCP bridges, and version-change detection
  • Teams already using Spectre.Console.Cli, or willing to add an export layer to an existing CLI

Scenarios Where Heavy Investment Isn’t Advised Yet

  • Public standard interfaces that must promise long-term compatibility to an external ecosystem
  • Scenarios that depend on seamless interoperability across multiple third-party implementations and cannot tolerate dialect risk
  • Foundational protocol layers with high requirements for version stability and governance maturity

Reallier’s Adoption Recommendation

We recommend treating OpenCLI as the middle layer of a three-tier structure:

  1. The CLI itself is the source-of-truth interface
  2. OpenCLI is the machine-readable description layer
  3. MCP / documentation portals / SDKs / shell completions are the downstream consumption layers

The benefits of this approach:

  • Only one contract needs to be maintained upstream
  • Downstream consumers can evolve independently
  • Even if OpenCLI changes later, risk can be contained through an adapter layer
  • Step 1: Inventory the existing CLI command surface, argument naming, and exit codes
  • Step 2: Generate an OpenCLI description for one high-value CLI first
  • Step 3: Wire it into documentation generation and breaking-change detection
  • Step 4: Then consider automating the OpenCLI → MCP bridge
  • Step 5: Roll it out across teams last

Primary Sources