clyops

Define your CLI once. Use it from terminals, desktop forms, HTTP and AI agents. clyops turns the options beside your code into a consistent, machine-readable contract. Keep the execution logic in your language; use the same tool through the terminal, the desktop runner, the HTTP API or an MCP client.

Register your options and arguments once at the top of a program, and clyops handles parsing, validation, help text, config files, environment variables, a JSON schema of the interface, logging helpers and shell completion for bash, zsh and fish.

See the animated project homepage or run the walkthrough: one small deployment-plan tool, from generated help to an agent call and an HTTP endpoint.

Try the mixed Bash/Python scripts immediately after cloning:

./examples/scripts/plan.py --env production --replicas 3
./examples/scripts/report.py --format table
./examples/scripts/transcode.sh examples/data/tone.wav /tmp/clyops-demo.m4a

No library compilation or pip dependencies are needed. FFmpeg and curl wrappers preview commands before explicit execution. The browser playground executes the Python examples in your tab.

The same behavior ships for Bash, JavaScript, TypeScript, Python, Rust, C, Go, Ruby and Java. Every implementation is checked against one shared specification and conformance suite, so a tool keeps the same help output, error messages and completion when you port it from Bash to Rust.

clyops_opt PORT port p 8080 "Server port" Network port                      # Bash

cli.opt('PORT', 'port', 'p', '8080', 'Server port', 'Network', 'port');    // JavaScript / TypeScript

cli.opt("PORT", "port", "p", "8080", "Server port", "Network", "port")       # Python

cli.opt("PORT", "port", "p", "8080", "Server port").group("Network").rule("port"); // Rust

clyops_opt(cli, "PORT", "port", "8080", .short_name = 'p', .description = "Server port", .group = "Network", .rule = "port"); // C

cli.Opt("PORT", "port", "p", "8080", "Server port", "Network", "port")       // Go

cli.opt "PORT", "port", "p", "8080", "Server port", "Network", "port"        # Ruby

cli.opt("PORT", "port", "p", "8080", "Server port", "Network", "port");     // Java

A complete program

<table> <tr><th>Bash</th><th>Python</th></tr> <tr><td>

#!/usr/bin/env bash
source clyops.sh

clyops_description "Copy files to a server."
clyops_arg          SRC   "File to send" "" "file:exists"
clyops_arg_variadic EXTRA "More files" "file:exists"
clyops_opt  HOST    host    H localhost "Server"  Network hostname
clyops_opt  PORT    port    p 22        "Port"    Network port
clyops_opt  VERBOSE verbose v flag      "Chatty"
clyops_opt  CONFIG  config  c optional  "Config file" Config path
clyops_config config "send:"
clyops_run "$@"

info "sending $SRC to $HOST:$PORT"

</td><td>

#!/usr/bin/env python3
from clyops import Cli, info

cli = Cli()
cli.set_description("Copy files to a server.")
cli.arg("SRC", "File to send", "", "file:exists")
cli.arg_variadic("EXTRA", "More files", "file:exists")
cli.opt("HOST", "host", "H", "localhost", "Server", "Network", "hostname")
cli.opt("PORT", "port", "p", "22", "Port", "Network", "port")
cli.opt("VERBOSE", "verbose", "v", "flag", "Chatty")
cli.opt("CONFIG", "config", "c", "optional", "Config file", "Config", "path")
cli.set_config("config", "send:")
args = cli.run()

info(f"sending {args.SRC} to {args.HOST}:{args.PORT}")

</td></tr> </table>

Each package's README shows the same program in its own language: JavaScript/TypeScript · Bash · Python · Rust · C · Go · Ruby · Java.

Either version (and the same program in every other language) prints exactly this for send --help:

Usage: send <SRC> [<EXTRA...>] [OPTIONS]

Copy files to a server.

Positional Arguments:
  SRC                           File to send (accepts: existing file)
  EXTRA                         More files (variadic, accepts: existing file)

Network:
  -H, --host=<value>            Server (default: localhost, accepts: hostname)
  -p, --port=<value>            Port (default: 22, accepts: port: 1-65535)

Options:
  -v, --verbose                 Chatty

Config:
  -c, --config=<value>          Config file (accepts: path)

Global:
  -h, --help                    Show this help message and exit

<details> <summary><code>send --help-json-schema</code>: the machine-readable interface that UIs, the API and the MCP server are built from</summary>

{
  "clyops": 1,
  "script": "send",
  "description": "Copy files to a server.",
  "epilog": "",
  "arguments": [
    {
      "name": "SRC",
      "description": "File to send",
      "required": true,
      "isVariadic": false,
      "default": "",
      "validation": "file:exists"
    },
    {
      "name": "EXTRA",
      "description": "More files",
      "required": false,
      "isVariadic": true,
      "default": "",
      "validation": "file:exists"
    }
  ],
  "options": [
    {
      "name": "host",
      "shortName": "H",
      "variableName": "HOST",
      "description": "Server",
      "default": "localhost",
      "group": "Network",
      "type": "string",
      "isFlag": false,
      "isArray": false,
      "required": false,
      "validation": "hostname",
      "choices": [],
      "secret": false
    },
    {
      "name": "port",
      "shortName": "p",
      "variableName": "PORT",
      "description": "Port",
      "default": "22",
      "group": "Network",
      "type": "integer",
      "isFlag": false,
      "isArray": false,
      "required": false,
      "validation": "port",
      "choices": [],
      "secret": false
    },
    {
      "name": "verbose",
      "shortName": "v",
      "variableName": "VERBOSE",
      "description": "Chatty",
      "default": "false",
      "group": "Options",
      "type": "boolean",
      "isFlag": true,
      "isArray": false,
      "required": false,
      "validation": "",
      "choices": [],
      "secret": false
    },
    {
      "name": "config",
      "shortName": "c",
      "variableName": "CONFIG",
      "description": "Config file",
      "default": "",
      "group": "Config",
      "type": "path",
      "isFlag": false,
      "isArray": false,
      "required": false,
      "validation": "path",
      "choices": [],
      "secret": false
    },
    {
      "name": "help",
      "shortName": "h",
      "variableName": "HELP",
      "description": "Show this help message and exit",
      "default": "false",
      "group": "Global",
      "type": "boolean",
      "isFlag": true,
      "isArray": false,
      "required": false,
      "validation": "",
      "choices": [],
      "secret": false
    }
  ],
  "requiredCommands": [],
  "effects": [],
  "constraints": [],
  "stdin": null,
  "stdout": null,
  "commands": []
}

</details>

What you get

| | | | --- | --- | | Parsing | --opt value, --opt=value, -o value, -ovalue, clustered flags -vq, --no-flag, -- to end options, repeatable array options, optional and variadic positionals | | Precedence | command line > config file > environment variable (named after the option's variable) > default | | Validation | int, int:1-10, float:0-1, string:1-8, choice:a,b, bool, port, ip, hostname, url, email, uuid, date:YYYY-MM-DD, regex:…, path, file:exists, file:readable, file:writable, dir:exists, dir:writable. Typed languages get converted values (PORT is an integer). | | Paths | path values become absolute, relative to wherever they came from: the cwd for the command line, the config file's directory for config values, the project root for defaults; optional search directories for bare names | | Config files | prefix:key=value lines, several prefixes per program, @include with cycle detection | | Help | generated --help, grouped and wrapped, showing defaults, accepted values and config values | | Introspection | --help-json-schema describes the whole interface (spec/schema.json) for UIs and tooling such as the runner | | Completion | --completion bash\|zsh\|fish prints a script that completes options, choices, files, directories and hosts | | Logging | info, warn, error, success, die with timestamps and colors (TTY only, NO_COLOR aware, CLYOPS_SILENT) | | Required commands | declare external tools a script needs; help shows whether each is installed | | Commands | nested subcommands in one program (mytool db migrate --to 3), each with its own options, arguments, help, schema and completion, sharing the program's options and config | | Relationships | exclusive, requires and oneOf between options, checked after config and environment, shown in help and the schema | | Secrets | a secret (or secret:RULE) option is masked in help and in the values JSON, and marked so the API, MCP server and runner keep it out of command lines, logs and templates | | Effects and I/O | declare what running the program does (read-only, idempotent, destructive, network) and what it reads on stdin and writes on stdout (with MIME types), for agents and servers to act on |

The spec is the precise reference for all of it.

Shell completion

The completion guide has copyable Bash, Zsh and Fish setup, including the example scripts and a dispatcher wrapper.

Every clyops program completes itself. Add one line to your shell startup:

eval "$(mytool --completion bash)"                                  # ~/.bashrc
eval "$(mytool --completion zsh)"                                   # ~/.zshrc, after compinit
mytool --completion fish > ~/.config/fish/completions/mytool.fish   # fish

The script asks the program for its options at completion time (mytool --bash-completion), so completion follows the code with no regeneration step.

clyops-dispatch

apps/dispatch turns a directory of tools into one command. A tiny definition file such as scripts/mytool

#!/usr/bin/env clyops-dispatch
description: mytool toolchain

makes every executable next to it a subcommand (mytool check) and every folder a group of subcommands (mytool media to-pcm), at any depth. mytool and mytool media list what's available with descriptions from each tool, and eval "$(mytool --completion bash)" (or zsh, fish) completes group and command names, then the chosen command's own options. Without a definition file, an alias does the same: alias mytool='clyops-dispatch --root ~/mytool/scripts --name mytool'. It ships as a native binary for Linux, macOS and Windows in each release.

Node tooling

packages/tools (clyops-tools) is the Node side of running clyops tools for someone else: it discovers a directory of tools the way clyops-dispatch does, reads their schemas, maps a JSON object onto a command line (spec §13) and gives the JSON Schema of that object. packages/jobs (clyops-jobs) runs tools as jobs: functions bound to tools in a JSON config, templated options, artifacts, job records and a queue.

clyops-api

apps/api serves a directory of tools over HTTP: clyops-api --root ~/mytool/scripts makes POST /tools/media/to-pcm run media/to-pcm.sh with a JSON body validated against the tool's schema, waiting for it or (?async=true) returning a job to poll, and publishes the whole thing as an OpenAPI document at /openapi.json. It serves the same tools to AI agents over MCP at /mcp. A non-JSON body is streamed to the tool's stdin, declared binary output