Create your spec file

Start by creating a YAML file that describes your CLI. We'll build a simple example called pleasantries — a CLI that can greet or bid farewell to someone.

Create a file called pleasantries-cli.ocs.yaml and begin with the version and metadata:

opencliVersion: "1.0.0-alpha.13"

# Metadata about your CLI"
info:
  title: "Pleasantries"
  summary: "A fun CLI to greet or bid farewell"
  version: "1.0.0"
  binary: "pleasantries"

The opencliVersion field specifies which version of the spec you're using. The info block contains human-readable metadata about your CLI — its name, description, version, and the binary name.

Define your commands

Next, add the commands section. Each command is a key that describes the invocation pattern, followed by its properties:

commands:
  # Group command - acts a container of subcommands
  pleasantries {command} <arguments> [flags]:
    kind: "group"

  # The 'greet' command
  pleasantries greet <name> [flags]:
    summary: "Say hello"
    args:
    - name: "name"
      summary: "A name to include in the greeting"
      required: true
      type: "string"
    flags:
    - name: "language"
      summary: "The language of the greeting"
      type: "string"
      choices:
      - value: "english"
      - value: "spanish"
      default: "english"

Here we define a greet command that takes a required <name> argument and an optional --language flag with choices.

Notice that we also defined the pleasantries which acts as a 'grouping' command. Defining grouping commands is optional - the code generation and docs generation will walk the command tree either way - but they can be a good way to help readability of the OpenCLI document and add additional comments.

Add examples

Make your spec more useful by adding example invocations:

    examples:
    - title: "greet the user"
      content:
        $ pleasantries greet --language english John
        # Hello, John

The complete spec with both commands (greet and farewell) is available in the examples directory.

Install the OpenCLI CLI

To validate your spec, install the ocli tool:

$ go install github.com/bcdxn/opencli/cmd/ocli@latest

This requires Go 1.21+ installed on your system. Once installed, you'll have the ocli command available.

Validate your spec

Run the check command to validate your document against the OpenCLI Specification:

$ ocli check ./pleasantries-cli.ocs.yaml
# ✓ pleasantries-cli.ocs.yaml is valid

If there are any issues, the CLI will report them with line numbers and descriptions. A valid spec means you're ready to generate documentation or code.