Everyone is wiring up MCP servers, Skills and agent tools right now.
That works fine when you have a handful of endpoints:
10
- endpoints = still manageable
100
- endpoints = annoying
- GitHub’s REST API with hundreds of endpoints = good luck keeping that tool zoo consistent over time
At the same time, a different pattern has become much more practical for agents: CLI wrappers.
So we took a different route with openapi-to-cli.
It takes an OpenAPI/Swagger spec from a URL or a local file and turns it into a CLI at runtime. No code generation. No compilation. One binary that can work with any HTTP API described by OpenAPI/Swagger.
What it does
Input:
- OpenAPI / Swagger spec from URL or file
- API base URL
- auth settings
- optional endpoint filters per profile
- Output:
- an ocli binary where each API operation becomes a CLI subcommand
- commands generated at runtime from the cached spec
Under the hood it:
- caches specs under .ocli/specs
- supports multiple profiles per API
- lets you include or exclude endpoints per profile
- lets you mount multiple APIs into the same binary
- lets you switch active profile with ocli use <profile>
Why use CLI commands instead of hundreds of MCP tools
If your agent has 100 tools, you can easily waste a huge chunk of context on JSON schemas alone.
With CLI, the shape is very different.
100 MCP tools:
- large schema payloads sitting in context
- extra server process and transport layer
- more overhead in tool selection
100 CLI commands:
- one shell-style execution tool
- agent discovers commands with search
- context stays focused on reasoning instead of tool metadata
The agent flow becomes:
- ocli commands --query "create pull request" --limit 5
- pick the best-ranked command
- execute it through a single shell tool
So instead of exposing hundreds or thousands of tools, you expose one command runner and let the agent discover the right command on demand.
Search for large APIs
Once an API gets big enough, --help stops being useful, so we added two discovery modes.
BM25 natural language search
ocli commands --query "create pull request" --limit 5
ocli commands --query "upload file" --limit 5
Regex search
ocli commands --regex "repos.*pulls"
Search matches command names, paths, descriptions, and parameter names.
According to the README, the BM25 engine is a TypeScript port of picoclaw and ranks across name, method, path, description, and parameters.
Multiple profiles and multiple APIs
The same API can have multiple profiles:
- read-only profile for safer agents
- write/admin profile for trusted workflows
Both profiles can share the same spec cache while exposing different endpoint sets.
You can also onboard completely different APIs into the same ocli binary and switch between them:
ocli use github
ocli commands --query "create pull request"
ocli use box
ocli commands --query "upload file"
Quick start
Install globally:
npm install -g openapi-to-cli
Or use it without a global install (it will create profile with name default):
npx openapi-to-cli onboard \
--api-base-url https://api.github.com \
--openapi-spec https://raw.githubusercontent.com/github/rest-api-description/main/descriptions-next/api.github.com/api.github.com.json
If you want a named profile (eg. github):
ocli profiles add github \
--api-base-url https://api.github.com \
--openapi-spec https://raw.githubusercontent.com/github/rest-api-description/main/descriptions-next/api.github.com/api.github.com.json
Then search and execute commands:
ocli use github
ocli commands --query "upload file" --limit 5
ocli repos_contents_put \
--owner yourname \
--repo yourrepo \
--path path/to/file.txt \
--message "Add file" \
--content "$(base64 < file.txt)"
Where this seems useful
- building agent toolchains without creating a giant MCP zoo
- letting an LLM call HTTP APIs through a single command-execution tool
- exploring third-party APIs quickly from a shell
- keeping the context window free for reasoning instead of tool metadata
One important caveat: ocli (v0.1.7) supports Basic and Bearer auth, but not OAuth2/Auth0 or Custom Header yet.
Sources: https://github.com/EvilFreelancer/openapi-to-cli
NPM: www.npmjs.com/package/openapi-to-cli
If you’re currently managing hundreds of MCPservers, Skill and tools, how much of that could realistically be replaced by one CLI plus search?
[link] [comments]
