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
• Benefits
• OpenCLI CLI
• Examples
• The Spec
• Releases
• Inspiration

Overview

OpenCLI specification is a document specification that can be used to describe CLIs. Spec-compliant documents are meant to be human-readable but the tooling supports documentation generation in a variety of formats.

Benefits

• Promote contract first development
• Decouple implementation of commands from the CLI Framework
• Automatically generate documentation your CLI
• Automatically generate CLI framework-specific code

OpenCLI CLI

Use the CLI to validate specs, generate docs and generate boilerplate code.

• Markdown Docs

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.7

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"
    arguments:
      - 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"
    arguments:
      - 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 \
  --spec-file ./cli.osc.yaml \
  --output-dir ./docs \
  --format markdown \
  --dryrun=false

You can see the generated documentation here.

Next, we can generate CLI Framework boilerplate code using the following command:

ocli gen cli \
  --spec-file ./cli.osc.yaml \
  --output-dir ./internal/cli \
  --framework urfavecli \
  --go-package cli \
  --dryrun=false

You can see the generated code here (go) and here (js).

OpenCLI CLI

The OpenCLI CLI uses an OpenCLI Spec and the OpenCLI CLI to generate it's own boilerplate code 🤯

• The spec that defines the OpenCLI CLI - here
• The markdown documentation automatically generated from the spec - here
• The boilerplate code generated from the spec
  • generated interface
  • generated framework boilerplate
  • generated parameter types

The Spec

The full spec is described by JSON Schema - https://github.com/bcdxn/opencli/tree/main/spec

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:
  • oapi-codegen
  • ogen
• Stripe's amazing looking CLI documentation