OpenCLI Specification

OpenCLI Specification asks the question that has been sitting unanswered next to OpenAPI for a decade: if an HTTP API gets a machine-readable contract, why does the command-line tool shipped alongside it get a --help string and nothing else. The answer proposed here is a direct transposition. A document declares opencli: 1.0.0, carries an info block, and then replaces OpenAPI’s paths with a commands tree — each command with a summary, an operationId, tags, parameters and responses. It validates against a JSON Schema (draft-07) published in the repository as opencli.spec.json, and it is Apache-2.0.

• Eight root properties, three of them required - opencli, info and commands are mandatory; externalDocs, platforms, environment, tags and components are optional. Five of those eight names are lifted straight from OpenAPI, which is the point — anyone who can read an API description can read this one without learning a new vocabulary.
• The two properties that are not from OpenAPI are the interesting ones - platforms declares which operating systems and architectures the tool ships for, and environment maps environment variables to CLI parameters. Neither has an HTTP analogue, and both are exactly the context an agent running a binary in a container needs and currently has to guess.
• Parameters model the things CLIs actually do - a parameter carries in: flag, alias for short forms, and scope: inherited for flags that apply down the whole subcommand tree. The definitions behind it are Platform, EnvironmentVariable, Tag, Command, Parameter, Schema, Response and MediaType — a small surface, deliberately.
• It describes itself - the site publishes opencli.json, a valid OpenCLI document describing the specification’s own ocs tool, complete with OCS_CONFIG_PATH and OCS_VERBOSE in the environment block. Self-description is the cheapest honest signal a specification can give, and this one gives it.
• The AI and MCP pitch is roadmap, not shipped - the project markets itself as “AI-native” and “MCP ready,” but the README’s own generator example is a commented-out line under the heading “Future vision,” and the working code it shows is a manual convertToMCPTools(cliSpec) you would write yourself. There is no reference generator, no conformance suite and no released tooling in the repository. Read the specification as a data format and ignore the ecosystem claims until something ships.
• The name is contested four ways, and this is the smallest claimant - opencli.org (spectreconsole/open-cli, “OCS”, 283 stars) and opencli.dev (bcdxn/opencli, 44 stars) are unrelated projects solving the same problem under the same name, and openclispec.com hosts a fourth, “OCLIS.” This entry covers openclispec.org — 9 stars, 2 forks, 39 commits, created 18 July 2025 and last pushed 29 October 2025. Anyone evaluating “OpenCLI” needs to establish which one is meant before comparing anything.
• “Working Group” and “Community” name nobody - the published document credits an “OpenCLI Working Group” and the site’s schema.org block a publisher called “OpenCLI Community.” Both resolve to a single personal GitHub repository with two contributors and no governance file, charter or membership. That is not disqualifying for a v1.0.0 format, but the institutional language is ahead of the institution.

For an API provider the relevant fact is not which OpenCLI wins. It is that the CLI has quietly become a primary consumption surface — agents shell out to gh, aws, stripe and your tool far more often than they hand-write an HTTP request — and that surface is the last major one in the stack with no contract behind it. OpenCLI describes what a CLI offers, in the shape of an API description. The CLI Agent Spec describes how a CLI must behave when a machine is the caller. They are the two halves of the same missing artifact, they were written independently and they do not reference each other — which tells you how early this is.