First run
End users · agent authors
You want commands that work. Start with the quickstart, understand the two binaries, then connect open-cli to a hosted runtime.
Governed OpenAPI execution, end to end.
open-cli-toolbox is the hosted runtime that discovers APIs, normalizes catalogs, resolves credentials, enforces policy, and writes audit events. open-cli is the thin client that renders commands and sends execution requests into that remote boundary.
The problem it solves
Most teams operate OpenAPI tooling with three unresolved gaps.
Scattered API descriptions
OpenAPI files live in repos, behind service-discovery endpoints, in registries. No two look the same; tool IDs clash; schemas drift between sources and reality.
Implicit, unaudited credentials
Auth tokens are pasted into config files or passed as env vars with no per-request resolution, no scope filtering, and no record of who authenticated as what.
No enforcement layer
Any CLI or agent can call any operation. There is no policy gate, no approval workflow, and no structured record of what executed — until something goes wrong.
open-cli-toolbox closes all three gaps — discovery, auth resolution, policy enforcement, and audit — before any command reaches the wire.
How it works
Three stages from raw OpenAPI to a governed, auditable command surface.
- Point at your sources
Local OpenAPI files, URLs, RFC 9727 catalogs, or RFC 8631 service-discovery endpoints. The hosted runtime finds and fetches them automatically.
- Runtime governs the catalog
open-cli-toolbox deduplicates and normalizes tool IDs, applies overlays, evaluates policy rules, and resolves per-request credentials before any execution occurs.
- Execute with confidence
Use open-cli commands or the built-in MCP server. Every tool call, approval decision, and auth event passes through the hosted runtime and lands in the audit trail.
Choose the path that matches why you are here
Each path links to the first doc that matters for your role — no hunting through unrelated sections.
Runtime depth
Operators · developers
You are hosting open-cli-toolbox, hardening a deployment, or wiring up auth, policy, and overlays for shared use.
Enterprise evaluation
Security reviewers · procurement
You need a reviewable evidence package: hosted-runtime auth proof, reproducible test artifacts, auditability, and known gaps.
Command surface
catalogList and inspect available tools from all discovered sources.explainShow schema, description, and parameter detail for any tool.workflowRun multi-step operations with declarative workflow definitions.dynamic-toolExecute individual OpenAPI operations directly from the CLI.MCP serverExpose the governed catalog over the Model Context Protocol for agent use.
Hosted runtime topologies
One supported model — a hosted runtime — with deployment shapes that scale from local evaluation to enterprise hosting.
Loopback-hosted runtime
Fastest way to evaluate
Run open-cli-toolbox on the same machine and point open-cli at http://127.0.0.1:8765. It is still the remote runtime contract, just hosted locally for development.
Trade-off: Single-user footprint; you manage process lifecycle and runtime URL wiring.
Deployment models →Shared team runtime
One hosted control plane
Host open-cli-toolbox on shared infrastructure so teams, agents, and automation all consume the same governed catalog, policy, cache, and audit boundary.
Trade-off: Requires network reachability planning, shared config ownership, and runtime auth.
Deployment models →Brokered enterprise runtime
Security boundary first
Put open-cli-toolbox behind IdP-issued bearer auth, reverse proxies, and network controls. This is the supported production model for enterprise access review.
Trade-off: You own external perimeter controls, token lifecycle policy, and runtime hosting.
Deployment models →CLI vs runtime: where enforcement lives
The CLI is a thin command surface. Enforcement — policy, auth, audit — lives in the runtime. This split is intentional: the CLI can be replaced or bypassed; the hosted runtime holds the invariants.
| Concern | CLI (open-cli) | Runtime (open-cli-toolbox) |
|---|---|---|
| Catalog visibility | Reads the effective catalog that the runtime built. | Applies mode filters, agent profiles, and policy rules at build time. |
| Auth resolution | Passes request context; does not hold secrets. | Resolves credentials from secret sources per request. |
| Execution approval | Surfaces approval prompts when the runtime requires them. | Evaluates approval gates defined in policy before executing. |
| Audit logging | No independent audit log. | Appends a structured event for every tool call, approval, and auth resolution. |
| Schema validation | Can validate request shape against the OpenAPI schema. | Validates against the normalized effective schema at execution time. |
Full details in the Security overview and Policy and approval.
Evidence for enterprise evaluation
Reproducible proof artifacts — not marketing claims. Each item links to a concrete doc or test fixture.
Authentik reference proof
A worked, reproducible example of runtime bearer auth brokered through Authentik. Documents client-credentials flow, scope filtering, and Entra federation. Not a vendor endorsement — a concrete test fixture.
View auth proof →Fleet validation matrix
CI-reproducible capability matrix covering hosted runtime auth, MCP, and remote API paths. Each cell maps to a concrete test artifact or known gap — no unverified claims.
View fleet matrix →Spec & conformance
OpenAPI overlay processing, RFC 9727 catalog support, and RFC 8631 service discovery are each tracked against the published spec. Conformance notes surface known gaps.
View discovery docs →Audit surfaces
The runtime appends a structured audit log entry for every tool execution, approval gate decision, and auth resolution. Log schema and retention are documented.
View security docs →Your first run
Start open-cli-toolbox, then drive it with open-cli. See the quickstart for installation and .cli.json setup.
# Start the hosted runtime once
open-cli-toolbox --config .cli.json --addr 127.0.0.1:8765
# In another shell, inspect the governed catalog
open-cli --runtime http://127.0.0.1:8765 --config .cli.json catalog list
# Inspect or execute a tool through the runtime boundary
open-cli --runtime http://127.0.0.1:8765 --config .cli.json explain tickets:listTickets