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.
Try the live OpenCLI Specification Editor
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.13
info:
title: Pleasantries
summary: A fun CLI to greet or bid farewell
version: 1.0.0
binary: pleasantries
commands:
pleasantries {command} <arguments> [flags]:
kind: group
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 OpenCLI document we can generate clean markdown documentation using the follow command:
ocli gen docs \
--format markdown \
--out ./docs \
./cli.osc.yamlWe can also generate embeddable HTML docs as a script bundle:
ocli gen docs \
--format html-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>We can also use the specification to generate boilerplate code for common CLI libraries:
ocli gen cli \
--framework cobra \
--out ./internal \
./cli.ocs.yamlCheck out the /examples directory examples documentation and code generated from OpenCLI documents.
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/validateAlready have a CLI? Use the packages here to generate OpenCLI documents from existing CLI codebases.
e.g., for urfavecli:
go get github.com/bcdxn/opencli/adapters/ourfaveThen add the provided __opencli command using the package.
func main() {
// Your existing CLI app
command := &cli.Command{
Name: "pleasantries",
Usage: "A fun CLI that greets the caller",
Commands: []*cli.Command{
// ...
},
}
// Add the hidden __opencli command
ourfave.FromCommand(command, ourfave.WithOutput(os.Stdout))
app := command.App()
app.Run(context.Background(), preprocessArgs(os.Args))
}Run the CLI to generate the OpenCLI document.
pleasantries __opencli
# opencliVersion: 1.0.0-alpha.13
# info:
# title: pleasantries
# summary: A fun CLI that greets the caller
# commands:
# ...The 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
If you use OpenCLI to document your CLI, show your support by adding the OpenCLI Compliant badge to your README:
To add your badge, copy the code below and add it to your README.md:
[](https://opencli.dev)