ring-cli -- YAML to CLI Generator

Build custom command-line tools from YAML configs or OpenAPI specs. Single static binary, zero runtime dependencies, automatic tab completion, nested subcommands, and trust-based security. Works on Linux, macOS, and Windows.

What Makes ring-cli Different

ring-cli is a CLI generator that turns YAML configs and OpenAPI specs into complete, production-ready command-line tools -- delivered as a single portable binary with zero dependencies.

No interpreters. No package managers. No frameworks. Drop it on any machine and start building CLIs immediately. The binary has no network capabilities -- it never phones home, never downloads anything on its own, and carries zero attack surface. Safe to run on production servers, CI runners, and air-gapped environments.

Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/MichaelCereda/ring-cli/master/install.sh | sh

Windows (PowerShell):

irm https://github.com/MichaelCereda/ring-cli/releases/latest/download/ring-cli-Windows-x86_64.zip -OutFile ring-cli.zip; Expand-Archive ring-cli.zip -DestinationPath $env:LOCALAPPDATA\ring-cli -Force; $env:PATH += ";$env:LOCALAPPDATA\ring-cli"

Homebrew (macOS / Linux):

brew install michaelcereda/ring-cli/ring-cli

From source:

cargo install ring-cli

Quick Start: From YAML

Define commands in a YAML file:

version: "2.0"
name: "deploy"
description: "Deployment operations"
commands:
  staging:
    description: "Deploy to staging"
    flags:
      - name: "branch"
        description: "Branch to deploy"
    cmd:
      run:
        - "echo Deploying ${{branch}} to staging"

Install as a shell alias:

ring-cli init --alias ops --config-path deploy.yml --description "Deployment tools"

Use it immediately:

$ ops
Deployment tools

Usage: ops [OPTIONS] [COMMAND]

Commands:
  deploy                 Deployment operations
  refresh-configuration  Re-read and trust updated configuration

$ ops deploy staging --branch main
$ ops <TAB>                   # tab completion at every level

Quick Start: From OpenAPI

Turn any OpenAPI 3.0 spec into a CLI:

ring-cli init --alias petstore \
  --config-path openapi:https://petstore3.swagger.io/api/v3/openapi.json \
  --description "Petstore API client"

$ petstore
Petstore API client

Usage: petstore [OPTIONS] [COMMAND]

Commands:
  petstore               Generated from OpenAPI spec: Petstore
  refresh-configuration  Re-read and trust updated configuration

$ petstore petstore pets list
$ petstore petstore pets get --pet-id 5
$ petstore petstore pets create --name "Buddy" --tag "dog"

Paths become commands. Parameters become flags. Request bodies become dot-notation flags. Authentication via environment variables. curl/wget for execution.

Multi-Config Composition

Combine multiple configs into one alias -- each becomes a top-level subcommand:

ring-cli init --alias infra \
  --config-path deploy.yml \
  --config-path db.yml \
  --config-path monitoring.yml \
  --description "Infrastructure management"

$ infra
Infrastructure management

Usage: infra [OPTIONS] [COMMAND]

Commands:
  deploy                 Build and deploy services to any environment
  db                     Database migrations, backups, and connectivity
  monitoring             Dashboards, alerts, and log queries
  refresh-configuration  Re-read and trust updated configuration

$ infra deploy staging --service api --branch main
$ infra db migrate --env production
$ infra monitoring alerts --team backend

Or use a references file to manage configs together:

# .ring-cli/references.yml
description: "Infrastructure management"
banner: "infra-cli v2.0"
configs:
  - deploy.yml
  - db.yml
  - monitoring.yml

Features

• Single Static Binary, Zero Dependencies -- One portable executable. No Java, Python, Node.js, or interpreters required. Drop on any server and start using immediately.

• YAML-Driven CLI Generation -- Define commands, flags, and subcommands in plain YAML. Supports shell commands, scripts, multi-step execution, and environment variable substitution.

• OpenAPI 3.0 Support -- Point ring-cli at an OpenAPI spec (local file or remote URL) and get a working CLI automatically. Paths become commands, parameters become flags, request bodies become dot-notation flags, curl/wget for execution.

• Tab Completion -- Bash, Zsh, Fish, and PowerShell completions installed automatically. Works at every level: top-level commands, nested subcommands, and flags.

• Multi-Config Composition -- Combine multiple YAML configs or OpenAPI specs into one alias. Each config becomes a top-level subcommand. Use references files to manage them together.

• Alias Descriptions -- Set a description for your alias via --description flag or description field in references files. Shown in help output when running the alias.

• Trust-Based Security -- Configs are cached with SHA-256 hashes and only run from your trusted cache. Use refresh-configuration to review changes before accepting them.

• Zero Network Footprint -- No HTTP client in the binary. OpenAPI specs are fetched via your own curl/wget with explicit consent. No callbacks, no analytics, no phone-home. Safe for production servers and air-gapped environments.

• Built for Automation -- Stdout/stderr separation for reliable piping. -q quiet mode, --yes for CI/CD, ASCII-only output, nonzero exit codes on error. Pre-built for Linux (x86_64, aarch64, ARM), macOS (Intel, Apple Silicon), and Windows (x86_64, ARM64).

• Variable Substitution -- ${{flag_name}} for command flags, ${{env.VAR_NAME}} for environment variables in your shell commands.

• Nested Subcommands -- Unlimited nesting depth. Organize complex CLIs into natural hierarchies.

• Claude Code Plugin -- Describe the CLI you want in plain English and the /ring-cli:configuration-builder skill generates the YAML config, installs it, and sets up tab completion. Also converts MCP server tools into standalone shell commands. See Claude Code Integration below.

• Standards Compliant -- Respects NO_COLOR env var. --color=always|never|auto override. -v verbose mode. Configurable banners on stderr.

Claude Code Integration

ring-cli ships with a Claude Code plugin that lets you generate CLI configurations from natural language. Describe the commands you need, and Claude builds the YAML config for you.

Install the plugin:

claude /plugin install --plugin-dir https://github.com/MichaelCereda/ring-cli/tree/master/plugin

Then use it in any project:

> /ring-cli:configuration-builder
> I need a CLI to manage my Docker stack: start, stop, logs, and deploy with an env flag

Claude generates the ring-cli YAML config, shows it for review, and installs it as a shell alias -- complete with tab completion.

The plugin also converts MCP server tools into shell commands. If you have MCP servers configured in Claude Code, it reads the tool definitions and generates equivalent ring-cli configs using real CLI tools (gh, docker, kubectl, etc.) wherever possible.

See the CLI Builder Guide for full details.

Use Cases

• DevOps Automation -- Build multi-command deployment tools from YAML without shell script complexity
• API Gateway CLI -- Convert OpenAPI specs into self-documenting CLI tools for your APIs
• Platform Engineering -- Distribute internal tools as single binaries to your team
• CI/CD Helpers -- Custom CLI tools for GitHub Actions, GitLab CI, or Kubernetes hooks
• AI-Assisted CLI Generation -- Describe what you need in plain English via the Claude Code plugin and get a working CLI
• MCP / AI Agent Tools -- Expose CLI operations to Claude, ChatGPT, or local LLMs
• SRE Automation -- Quick incident response tools without learning new frameworks
• Infrastructure-as-Code -- Generate CLI wrappers around Terraform, CloudFormation, or Ansible

Documentation

• Getting Started Guide -- Detailed walkthrough and configuration format
• Configuration Reference -- Complete YAML schema and field descriptions
• OpenAPI Guide -- OpenAPI specs, flag mapping, authentication, limitations
• CLI Builder Guide -- Using the /ring-cli:configuration-builder Claude Code plugin
• Setup Guide -- Installation from source, platform notes, troubleshooting

License

MIT