# Ocli API

> Turn any OpenAPI/Swagger API into CLI commands and call them. Search endpoints with BM25, check parameters, execute — no MCP server needed.

- Skill: `evilfreelancer/ocli-api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add evilfreelancer/ocli-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evilfreelancer/ocli-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: EvilFreelancer (https://skillmd.com/u/evilfreelancer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/evilfreelancer/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)

```bash
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:
   ```bash
   ocli commands --query "your task description" --limit 5
   ```
2. **Check parameters** of the chosen command:
   ```bash
   ocli <command> --help
   ```
3. **Execute** the command:
   ```bash
   ocli <command> --param1 value1 --param2 value2
   ```
4. **Parse** the JSON response and act on the result.

## Search options

```bash
# 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

```bash
# 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.