Define your Command Line Interface (CLI) in a declarative, language-agnostic document that can be used to generate documentation and boilerplate code.
Like OpenAPI Spec, but for your CLIs
OpenCLI specification is a document specification that can be used to describe CLIs. Spec-compliant documents are meant to be human-readable and enable tooling automation.
- Promote contract first development
- Decouple implementation of commands from the CLI Framework
- Automatically generate documentation your CLI
- Automatically generate CLI framework-specific code
- Improve LLM and agent understanding of your CLI
Use the CLI to validate specs, generate docs and generate boilerplate code.
Let's describe the following CLI
$ pleasantries greet John --language=english
# hello John
$ pleasantries farewell Jane --language=spanish
# adios JaneThe CLI above can be described using an OpenCLI Specification Document in YAML (or JSON):
# cli.yaml
opencliVersion: 1.0.0-alpha.8
info:
title: Pleasantries
summary: A fun CLI to greet or bid farewell
version: 1.0.0
binary: pleasantries
commands:
pleasantries {command} <name> [flags]:
group: true
pleasantries greet <name> [flags]:
summary: "Say hello"
args:
- name: "name"
summary: "A name to include the greeting"
required: true
type: "string"
flags:
- name: "language"
summary: "The language of the greeting"
type: "string"
choices:
- value: "english"
- value: "spanish"
default: "english"
pleasantries farewell <name> [flags]:
summary: "Say goodbye"
args:
- name: "name"
summary: "A name to include in the farewell"
required: true
type: "string"
flags:
- name: "language"
summary: "The language of the greeting"
type: "string"
choices:
- value: "english"
- value: "spanish"
default: "english"From this example we can generate documentation using the follow command:
ocli gen docs \
--format markdown \
--out ./docs \
./cli.osc.yamlTo generate embeddable HTML docs as a script bundle:
ocli gen docs \
--format html \
--html-flavor embed \
--out ./docs \
./cli.ocs.yamlThis writes ./docs/ocli-docs.js. You can then mount it in any page:
<html>
<head>
<script src="./assets/ocli-docs.js"></script>
</head>
<body>
<div id="docs"></div>
<script>
window.OcliDocs({ containerId: "docs" });
</script>
</body>
</html>Don't want to use the CLI, and instead prefer library integration? You can use the the following packages:
Use this package to marshal and unmarshal OpenCLI Spec compliant documents
go get github.com/bcdxn/opencli/codecUse this package to validate OpenCLI Spec compliant documents
go get github.com/bcdxn/opencli/validateThe full spec is described by JSON Schema - https://github.com/bcdxn/opencli/tree/main/spec.schema.json
Not all rules can be adequately expressed in JSON Schema alone. Additional validation logical is implemented in the validate package.
Start using OpenCLI Specification Documents to describe your CLIs. Head over to the releases page to download the CLI for your system.
- OpenAPI Specification
- Code generation tools like:
- Stripe's amazing looking CLI documentation
- All of the incredible CLI Frameworks