Skip to content

draft.md

Latest commit

 

History

History
216 lines (161 loc) · 9.26 KB

draft.md

File metadata and controls

216 lines (161 loc) · 9.26 KB

OpenCLI Specification

Version 0.1

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC2119, and RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under the MIT license

Change log
Date Author Description
2026-03-24 Bob Lail Add default value for arity to Argument Object
2025-07-15 Patrik Svensson Added interactive to root command and commands
2025-07-16 Patrik Svensson Added Metadata Object
2025-07-16 Patrik Svensson Changed maps to arrays
2025-07-18 Patrik Svensson name property in License Object is no longer required
2025-08-06 Patrik Svensson Remove ordinal property from Argument Object
2025-08-06 Patrik Svensson Add recursive property to Option Object
2025-08-06 Patrik Svensson Add summary property to CliInfo Object
2025-10-04 Patrik Svensson Add default values to schema

Introduction

The OpenCLI specification (OCS) defines a standard, platform and language agnostic interface to CLI applications which allows both humans and computers to understand how a CLI tool should be invoked without access to source code or documentation.

An OpenCLI Description can be used by documentation software to display usage of a tool, or code generation tools to create clients for interoping with a CLI tool.

In short, an OpenCLI description can be used for the following:

  • Create documentation for CLI tools
  • Generate clients for interacting with CLI tools
  • Automate external tools such as MCP servers
  • Detect changes in CLI APIs
  • Generate auto-completion scripts

This specification is heavily influenced by the OpenAPI specification.

Definitions

OpenCLI Description

An OpenCLI Description is a single JSON or YAML document that conforms to the OpenCLI Specification.

CLI

Command Line Application. A text based interface to an application.

Schema

A "schema" is a formal description of syntax and structure.

Object

When capitalized, the word "Object" refers to any of the Objects that are named by section headings in this document.

Case sensitivity

All field names in the OpenCLI specification are case sensitive unless otherwise stated.

Arity

The number of argument values an option expect.

Specification

Versions

The OpenCLI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 1.1) SHALL designate the OCS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OCS 1.1 SHOULD be compatible with all OCS 1.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.1.0 and 1.1.1 for example.

Ordering

The ordering of items within arrays MUST be considered normative.

Schema

This section describes the structure of the OpenCLI Description format. This text is the only normative description of the format.

Document Object

This is the root object of the OpenCLI Description.

Field Name Type Default Value Description
opencli string - REQUIRED The OpenCLI version number
info CliInfo Object - REQUIRED Information about the CLI
conventions Conventions Object - The conventions used by the CLI
arguments [Argument Object] - Root command arguments
options [Option Object] - Root command options
commands [Command Object] - Root command sub commands
exitCodes [ExitCode Object] - Root command exit codes
examples [string] - Examples of how to use the CLI
interactive bool false Indicates whether or not the command requires interactive input
metadata [Metadata Object] - Custom metadata

CliInfo Object

Field Name Type Default Value Description
title string - REQUIRED The application title
summary string - A short summary of the application
description string - A description of the application
contact Contact Object - The contact information
license License Object - The application license
version string - REQUIRED The application version

Conventions Object

Field Name Type Default Value Description
groupOptions bool true Whether or not grouping of short options are allowed
optionArgumentSeparator string U+0020 (space) The option argument separator

Contact Object

Field Name Format Default Value Description
name string - The identifying name of the contact person/organization
url string - The URI for the contact information. This MUST be in the form of a URI
email string - The email address of the contact person/organization. This MUST be in the form of an email address

License Object

Field Name Type Default Value Description
name string - The license name
identifier string - The SPDX license identifier
url string - The URI for the license. This MUST be in the form of a URI

Command Object

Field Name Type Default Value Description
name string - REQUIRED The command name
aliases [string] - The command aliases
options [Option Object] - The command's options
arguments [Argument Object] - The command's arguments
commands [Command Object] - The command's sub commands
exitCodes [ExitCode Object] - The command's exit codes
description string - The command description
hidden bool false Whether or not the command is hidden
examples [string] - Examples of how to use the command
interactive bool false Indicates whether or not the command requires interactive input
metadata [Metadata Object] - Custom metadata

Argument Object

Field Name Type Default Value Description
name string - REQUIRED The argument name
required bool false Whether or not the argument is required
arity Arity Object {"minimum": 1, "maximum": 1} The argument arity. Arity defines the minimum and maximum number of argument values
acceptedValues [string] - A list of accepted values
group string - The argument group
description string - The argument description
hidden bool false Whether or not the argument is hidden
metadata [Metadata Object] - Custom metadata

Option Object

Field Name Type Default Value Description
name string - REQUIRED The option name
required bool false Whether or not the option is required
aliases [string] - The option's aliases
arguments [Argument] - The option's arguments
group string - The option group
description string - The option description
recursive bool false Specifies whether the option is accessible from the immediate parent command and, recursively, from its subcommands
hidden bool false Whether or not the option is hidden
metadata [Metadata Object] - Custom metadata

Arity Object

Field Name Type Default Value Description
minimum int 1 The minimum number of values allowed
maximum int 1 The maximum number of values allowed. If not specified (nil), unlimited number of items are allowed

ExitCode Object

Field Name Type Default Value Description
code int - REQUIRED The exit code
description string - The exit code description

Metadata Object

Field Name Type Default Value Description
name string - REQUIRED The metadata name
value object - The metadata value