ocli-api

ocli — OpenAPI to CLI

Call any HTTP API described by an OpenAPI/Swagger spec as CLI commands. No MCP server, no code generation, no JSON schemas in context.

When to use

• You need to call a REST API (internal, cloud, SaaS)
• You have an OpenAPI or Swagger spec (URL or local file)
• You want minimal token overhead (1 tool, ~158 tokens/turn)

Setup (one-time)

npm install -g openapi-to-cli

ocli profiles add <name> \
  --api-base-url <BASE_URL> \
  --openapi-spec <SPEC_URL_OR_PATH> \
  --api-bearer-token "$TOKEN"

ocli use <name>

Workflow

1. Search for the right command:

   ocli commands --query "your task description" --limit 5
   

2. Check parameters of the chosen command:

   ocli <command> --help
   

3. Execute the command:

   ocli <command> --param1 value1 --param2 value2
   

4. Parse the JSON response and act on the result.

Search options

# BM25 natural language search
ocli commands --query "upload file to storage" --limit 5

# Regex pattern search
ocli commands --regex "users.*post" --limit 10

# List all commands
ocli commands

Multiple APIs

# Switch active profile
ocli use github

# Or specify per-call
ocli repos_get --profile github --owner octocat --repo Hello-World

Guardrails

• Always search before guessing a command name.
• Always check --help before calling a command you haven't used before.
• Never fabricate parameter names — use the ones from --help output.
• If a command returns an error, read the response body before retrying.

Failure handling

• Command not found: re-search with different keywords or use --regex.
• Missing required parameter: run --help and add the missing flag.
• Unknown option: the flag is not defined by the command; copy the exact name from --help, including a leading $ when the spec uses one (--$expand).
• 401/403: check that the profile has a valid token (ocli profiles show <name>).
• Spec not loaded: run ocli profiles add again with --openapi-spec to refresh cache.