opencli

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

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 itself 🤯

• 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