README
¶
OpenCLI Specification
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
Table of Contents
Overview
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.
Benefits
- 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
OpenCLI CLI
Use the CLI to validate specs, generate docs and generate boilerplate code.
Live Editor
Try the live OpenCLI Specification Editor
Examples
Pleasantries CLI
Let's describe the following CLI
$ pleasantries greet John --language=english
# hello John
$ pleasantries farewell Jane --language=spanish
# adios Jane
The 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"
Generating Documentation
From this OpenCLI document we can generate clean markdown documentation using the follow command:
ocli gen docs \
--format markdown \
--out ./docs \
./cli.osc.yaml
We can also generate embeddable HTML docs as a script bundle:
ocli gen docs \
--format html-embed \
--out ./docs \
./cli.ocs.yaml
This 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>
Generating Code
We can also use the specification to generate boilerplate code for common CLI libraries:
ocli gen cli \
--framework cobra \
--out ./internal \
./cli.ocs.yaml
Check out the /examples directory examples documentation and code generated from OpenCLI documents.
Packages
Don't want to use the CLI, and instead prefer library integration? You can use the the following packages:
codec
Use this package to marshal and unmarshal OpenCLI Spec compliant documents
go get github.com/bcdxn/opencli/codec
validate
Use this package to validate OpenCLI Spec compliant documents
go get github.com/bcdxn/opencli/validate
adapters/*
Already 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/ourfave
Then 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 Spec
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.
Releases
Start using OpenCLI Specification Documents to describe your CLIs. Head over to the releases page to download the CLI for your system.
Inspiration
- OpenAPI Specification
- Code generation tools like:
- Stripe's amazing looking CLI documentation
- All of the incredible CLI Frameworks
Badges
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)
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
ocobra
Package ocobra provides the ability to create OpenCLI documents from existing Cobra CLIs.
|
Package ocobra provides the ability to create OpenCLI documents from existing Cobra CLIs. |
|
ourfave
Package ourfave provides the ability to create OpenCLI documents from existing urfave/cli v3 CLIs.
|
Package ourfave provides the ability to create OpenCLI documents from existing urfave/cli v3 CLIs. |
|
cmd
|
|
|
ocli
command
Package main creates an entrypoint for the `ocli` CLI.
|
Package main creates an entrypoint for the `ocli` CLI. |
|
wasm
command
|
|
|
Package codec provides capabilities for marshalling and unmarshalling OpenCLI documents.
|
Package codec provides capabilities for marshalling and unmarshalling OpenCLI documents. |
|
examples
|
|
|
code/gencli
Code generated by github.com/bcdxn/opencli@unknown version DO NOT EDIT.
|
Code generated by github.com/bcdxn/opencli@unknown version DO NOT EDIT. |
|
Package gen contains funtions to generate documentation and framework-specific boilerplate code from a valid OpenCLI specification document.
|
Package gen contains funtions to generate documentation and framework-specific boilerplate code from a valid OpenCLI specification document. |
|
internal
|
|
|
cli/gencli
Code generated by github.com/bcdxn/opencli@unknown version DO NOT EDIT.
|
Code generated by github.com/bcdxn/opencli@unknown version DO NOT EDIT. |
|
Package validate provides validation capabilities for OpenCLI specification documents.
|
Package validate provides validation capabilities for OpenCLI specification documents. |
|
web
|
|