First run
End users · agent authors
You want commands that work. Start with the quickstart, understand the two binaries, then run your first tool.
Governed OpenAPI execution, end to end.
oclird discovers your APIs, normalises them, resolves credentials, enforces policy, and writes an audit log — so ocli and your agents always work against a clean, governed catalog.
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.
oclird 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 runtime finds and fetches them automatically.
- Runtime governs the catalog
oclird deduplicates and normalises tool IDs, applies OpenAPI overlays, evaluates policy rules, and resolves per-request credentials — before any execution occurs.
- Execute with confidence
Use ocli commands or the built-in MCP server. Every tool call, approval gate decision, and auth event is appended to a structured audit log.
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 configuring a reusable daemon, hardening a deployment, or wiring up auth, policy, and overlays.
Enterprise evaluation
Security reviewers · procurement
You need a reviewable evidence package: real 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.
Deployment modes
Three topologies — pick the one that matches your operational context.
Embedded
No daemon required
The runtime runs in-process for each ocli invocation. Zero setup, no background process, ideal for developer laptops and CI.
Trade-off: Cold start on every call; no shared cache across invocations.
Deployment models →Local daemon
Shared, warmed runtime
A single oclird process persists across CLI calls. Catalog is discovered once, cached, and reused. Supports instance isolation via --instance-id.
Trade-off: Requires a running daemon; process management is your responsibility.
Deployment models →Remote runtime
Centrally hosted
oclird runs on a shared host. Access is network-controlled with runtime bearer auth. Suitable for teams and fleet deployments.
Trade-off: Network dependency; auth must be configured; trust boundary shifts to the host.
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 runtime holds the invariants.
| Concern | CLI (ocli) | Runtime (oclird) |
|---|---|---|
| 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 local daemon, remote runtime, 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
Three commands from install to executed tool — no daemon required. See the quickstart for installation and .cli.json config setup.
# Embedded mode — no daemon needed for a first run
ocli --embedded --config .cli.json catalog list
# Inspect a tool's schema and usage guidance
ocli --embedded --config .cli.json explain tickets:listTickets
# Execute a tool — dynamic commands are shaped by your OpenAPI spec
ocli --embedded --config .cli.json helpdesk tickets list-tickets --status open