OpenCLI

A CLI for working with OpenCLI Specs

ocli is a command line interface designed to make working with OpenCLI Spec documents easier. It provides a number of capabilities, including:

• validating OpenCLI Spec documents
• generating Documentation from OpenCLI Spec documents

The commands are documented below. You can also find out more about each command using the contextual --help flag. e.g.:

ocli gen --help

License

MIT

Contact

OpenCLI Team
https://github.com/bcdxn/opencli

Install

Binary Download

You can visit the GitHub releases page of the project to download pre-compiled binaries appropriate for your system.

https://github.com/bcdxn/opencli/releases

Go Install

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

Homebrew

Install the openclidev tap

brew tap openclidev/tap

Trust the tap

brew trust openclidev/tap

Now you're ready to install ocli using homebrew

brew install ocli

Configuration

Type	Path
YAML	~/.ocli/config.yaml

Exit Codes

• 0 OK - The command was successful
• 1 INTERNAL_CLI_ERROR - The command failed
• 2 BAD_USER_INPUT_ERROR - Missing or invalid input

Global Flags

--help

contextual help

boolean

--version

print the version of the CLI

boolean

---

Commands

$ ocli check <arguments> [flags]

Check an OpenCLI Spec document for errors

The check command will validate an OpenCLI Spec document and return any errors that are found.

Arguments

<path-to-spec>

The path to the OpenCLI Spec document to check

this command will check the validity of the given OpenCLI document by parsing it and checking it against the OpenCLI Specification.

string

Flags

--fail-on-err

Return a non-zero exit code if validation fails

boolean default:true

Examples

# Validate a spec document

$ ocli check ./examples/petstore-cli.ocs.yaml
# ✓ Checking ./examples/petstore-cli.ocs.yaml
#   Format: yaml
# ✓ Document is valid

---

$ ocli gen {command} <arguments> [flags]

grouping

Collection of commands used to generate code/docs from an OpenCLI Spec document

---

$ ocli gen docs <arguments> [flags]

Generate documentation

The ocli gen docs command will generate documentation from an OpenCLI Spec document. You can specify the format of the documentation to be generated using the --format flag.

Arguments

<path-to-spec>

Path to the OpenCLI Spec document

string

Flags

--format

The format of the documentation to generate

string enum

Supported Values of --format

• markdown - Plain text using standard Markdown.
• html-page - Full standalone HTML document
• html-embed - An embeddable js bundle including CSS and HTML
• man - Man Page using standard groff

Alternative Sources

• env:$OCLI_DOCS_FORMAT
• file:$.docs.format

--out

The path to the directory where the generated docs will be written

string default:./docs

--no-footer

Do not include the footer in the docs

boolean

--no-badge

Do not include the OpenCLI badge

boolean

Examples

# generate markdown docs

$ ocli gen docs -f markdown ./my-cli.ocs.yaml
# → Reading spec:       ./my-cli.ocs.yaml
# → Generating docs:    format=markdown, output=./docs
# ✓ Documentation written to: docs/my-cli.ocs.md

---

$ ocli gen cli <arguments> [flags]

Generate CLI Boilerplate code

The ocli gen cli command will generate the boilerplate code for various CLI frameworks from an OpenCLI Spec document.

Arguments

<path-to-spec>

The spec used to generate the code

string

Flags

--out

The path to the directory where the generated code will be output

string

--framework

The framework of the CLI boilerplate to generate

string enum

Supported Values of --framework

• cobra - Cobra a powerful, battle-tested CLI framework for Go
• urfavecli - urfave/cli is a declarative, simple, fast, and fun package for building command line tools in Go
• yargs - yargs be a node.js library fer hearties tryin' ter parse optstrings

Alternative Sources

• env:$OCLI_CLI_FRAMEWORK
• file:$.cli.framework

Examples

# generate Cobra (Go) CLI

$ ocli gen cli \
  --framework cobra \
  --out ./internal \
  ./my-cli.ocs.yaml
# → Reading spec:        ./my-cli.ocs.yaml
# → Generating CLI code: framework=cobra, output=./internal
# ✓ CLI Code written to: ./internal

# generate urfave/cli (Go) CLI

$ ocli gen cli \
  --framework urfavecli \
  --out ./internal \
  ./my-cli.ocs.yaml
# → Reading spec:        ./my-cli.ocs.yaml
# → Generating CLI code: framework=urfavecli, output=./internal
# ✓ CLI Code written to: ./internal

# generate Yargs (Node.JS) CLI

$ ocli gen cli \
  --framework yargs \
  --out ./src \
  ./my-cli.ocs.yaml
# → Reading spec:        ./my-cli.ocs.yaml
# → Generating CLI code: framework=yargs, output=./src
# ✓ CLI Code written to: ./src

---