opencli

module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT

README

banner

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

Go Reference OpenSSF Best Practices OpenCLI Compliant CI Codecov Mentioned in Awesome Go GitHub Repo stars

Install the CLI

Homebrew
$ brew install openclidev/tap # https://github.com/openclidev/homebrew-tap
$ brew trust openclidev/tap
$ brew install ocli
# ...
$ ocli --version
# ocli version 1.1.4
Binary

You can also go to our releases page to download platform specific binaries.

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

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

Currenly supported formats include:

  • Markdown: clean deterministic markdown docs ready for GitHub or anywhere that renders markdown
  • Man Pages: Properly formatted groff files that can be interpretted by man
  • HTML: Rich, interactive docs as a standalone web page or as an embedded component.

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

Badges

If you use OpenCLI to document your CLI, show your support by adding the OpenCLI Compliant badge to your README:

OpenCLI Compliant

To add your badge, copy the code below and add it to your README.md:

[![OpenCLI Compliant](https://img.shields.io/badge/OpenCLI_Spec-Compliant-brightgreen?link=https%3A%2F%2Fgithub.com%2Fbcdxn%2Fopencli)](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/app
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.
ds
Package validate provides validation capabilities for OpenCLI specification documents.
 Package validate provides validation capabilities for OpenCLI specification documents.
web
public/assets/code

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.