Reference
CLI reference
Every flag for the klaridian CLI, generated from the real commands.
klaridian generate
Generate an MCP server from an OpenAPI spec, optionally instrumented with one or more observability plugins
Required
| Flag | What it does |
|---|---|
--spec <path> | Path to the OpenAPI spec (JSON or YAML) |
--out <dir> | Output directory for the generated server |
Basics
| Flag | What it does |
|---|---|
--name <name> | Name for the generated server (default: derived from the spec's info.title) |
--base-url <url> | Override the API base URL (required if the spec's servers[] is relative/missing) |
--server-description <text> | Short human-readable description for the emitted server.json (distinct from individual tool descriptions) |
--force | Overwrite --out even if it already exists and is non-empty (default: refuse, to avoid silently destroying unrelated files) |
--json | Print a single machine-readable JSON result to stdout instead of human-readable progress lines on stderr (success or failure, always exactly one JSON value, exit code still reflects success) |
--quiet | Suppress step-by-step progress messages; still prints warnings, errors, and the final summary/next-steps line |
Security
See Security for the full guide.
| Flag | What it does |
|---|---|
--allow-external-refs | Allow resolving REMOTE http(s) external $ref pointers in the spec (default: refuse, to prevent SSRF from a malicious spec fetching attacker-controlled or internal URLs at generation time). Local-file $refs always resolve regardless. |
Lifecycle
See Lifecycle for the full guide.
| Flag | What it does |
|---|---|
--install | After generating, also run npm install --no-audit --no-fund and npm run build in --out (skips the manual step normally printed in "Next"). The generated project still needs npm start or klaridian start to actually run it. |
Configuration
See Configuration for the full guide.
| Flag | What it does |
|---|---|
--config <path> | Path to a klaridian.config.json file providing default values for other flags (overridden by any flag explicitly passed on the command line). Auto-discovered in the current directory if present. |
Curation
See Curation for the full guide.
| Flag | What it does |
|---|---|
--include-tags <tags> | Only include operations with at least one of these OpenAPI tags (comma-separated) |
--exclude-tags <tags> | Exclude operations with any of these OpenAPI tags (comma-separated) |
--exclude-operation-ids <ids> | Exclude these specific operationIds regardless of tags (comma-separated) |
--include-paths <patterns> | Only include operations whose path matches at least one of these regex patterns (comma-separated). Works even when the spec has zero OpenAPI tags, composes with --include-tags (both must pass). |
--exclude-paths <patterns> | Exclude operations whose path matches any of these regex patterns (comma-separated) |
--include-methods <methods> | Only include operations using one of these HTTP methods (comma-separated, for example get,post) |
--exclude-methods <methods> | Exclude operations using any of these HTTP methods (comma-separated) |
--interactive | Prompt for which tags to include before generating. Requires an interactive terminal, fails loudly if stdin is not a TTY (for example, running in CI or under an agent) instead of silently accepting empty input. |
Architecture
See Architecture for the full guide.
| Flag | What it does |
|---|---|
--architecture <id> | tools (default) emits one MCP tool per OpenAPI operation; code-mode emits two tools (search_docs, execute_code): the model writes TypeScript against a typed client, run in a Deno-sandboxed subprocess (TypeScript and Python servers alike), for large APIs where one-tool-per-operation is the wrong default. Requires an absolute --base-url (or an absolute server URL in the spec). |
Target language
See Target language for the full guide.
| Flag | What it does |
|---|---|
--language <lang> | Target language for the generated server: typescript (default) or python |
Plugins
See Plugins for the full guide.
| Flag | What it does |
|---|---|
--plugin <id> | Observability plugin to enable, repeatable (available: otel, posthog, amplitude, mixpanel) |
--plugin-config <keyvalue...> | Plugin config in <pluginId>.<key>=<value> form, repeatable |
Licensing
See Licensing for the full guide.
| Flag | What it does |
|---|---|
--license <id> | License for the generated server: mit, apache-2.0, none. Defaults to mit. |
--author <name> | Author/copyright holder name for the generated LICENSE file (default: your git user.name, or "the project author" if unset) |
Transport
See Transport for the full guide.
| Flag | What it does |
|---|---|
--transport <type> | Transport for the generated server: stdio (default) or streamable-http |
--port <number> | Port for the generated server when --transport is streamable-http (default: 3000) |
Upstream auth
See Upstream auth for the full guide.
| Flag | What it does |
|---|---|
--forward-headers <names> | Comma-separated inbound HTTP header names the generated server forwards to the upstream API (enables per-user upstream credentials via MCP client headers). Requires --transport streamable-http (stdio has no inbound HTTP headers). |
--auth-hook | Emit an editable pre-auth hook file (src/auth-hook.ts or auth_hook.py) the generated server calls before built-in auth. If the hook returns true, built-in auth is skipped — an escape hatch for exotic auth schemes. |
OAuth
See OAuth for the full guide.
| Flag | What it does |
|---|---|
--oauth-issuer <url> | OAuth 2.1 issuer URL of the external Authorization Server (IdP) protecting this server. Requires --transport streamable-http. The generated server acts ONLY as a resource server (RFC 9728 PRM, bearer-token/audience validation), never as an authorization server. |
--oauth-jwks-uri <url> | JWKS URI to fetch the IdP's signing keys from. When omitted, resolved automatically from --oauth-issuer's OIDC discovery document (<issuer>/.well-known/openid-configuration) at generation time. |
--oauth-audience <uri> | Expected token audience (RFC 8707), the canonical URI this server will be reachable at, for example https://mcp.example.com/mcp. Required with --oauth-issuer; tokens not bound to this exact value are rejected. |
--oauth-required-scopes <scopes> | Comma-separated OAuth scopes required on every tool call (default: none beyond token validity) |
MCP Registry
See MCP Registry for the full guide.
| Flag | What it does |
|---|---|
--registry-name <name> | Reverse-DNS name for the official MCP Registry, for example io.github.<you>/<server>. When set, the emitted server.json and package.json mcpName use it, and the project is emitted as publishable (package.json is not private and server.json declares an npm packages[] entry). |
--server-version <version> | Semantic version (for example 1.2.3) stamped onto the generated server's package.json, server.json, and runtime. Defaults to the spec's info.version if it is valid SemVer, otherwise 1.0.0. The MCP Registry requires a concrete SemVer string (no ranges). |
klaridian init
Interactive wizard that scaffolds a klaridian.config.json for klaridian generate (writes the file only — it does not generate a server)
Options
| Flag | What it does |
|---|---|
--out <path> | Where to write the config file (default: ./klaridian.config.json in the current directory) |
--force | Overwrite the config file even if it already exists (default: refuse, to avoid silently replacing one you meant to keep) |
--json | Print a single machine-readable JSON result to stdout instead of human-readable progress on stderr. Implies non-interactive: every wizard answer must come from a flag. |
--quiet | Suppress step-by-step progress messages; still prints warnings, errors, and the final next-steps line |
Wizard fields
See Wizard fields for the full guide.
| Flag | What it does |
|---|---|
--spec <path> | OpenAPI spec path or URL (skips that prompt when passed) |
--generate-out <dir> | Output directory klaridian generate should write the server to — the config file's out field, distinct from this command's own --out (skips that prompt when passed) |
--plugin <id> | Observability plugin to enable, repeatable (available: otel, posthog, amplitude, mixpanel); skips that prompt when passed |
--license <id> | License for the generated server: mit, apache-2.0, none (skips that prompt when passed). Defaults to mit. |
--transport <type> | Transport for the generated server: stdio or streamable-http (skips that prompt when passed). Defaults to stdio. |
klaridian start
Launch a server previously produced by klaridian generate — runs it in place (npm start for a TypeScript project, the .venv interpreter on server.py for a Python one). Generates and configures nothing; pass every generation flag (--spec, --language, --architecture, --plugin, ...) to generate instead, once, when you create or regenerate the project.
Options
See Options for the full guide.
| Flag | What it does |
|---|---|
--json | If a pre-launch check fails (missing/unbuilt project), print a single JSON error object to stdout instead of a human message. Has no effect once the server itself starts — from that point the server owns stdout. |
klaridian deploy
Emit deploy artifacts for a project previously produced by klaridian generate. Uses the emit + shell-out model: klaridian writes the platform's native config (a portable Dockerfile for --target docker) rather than reimplementing deploy infrastructure. Reconfigures nothing about the server itself — every structural decision was made at generation time. Requires a streamable-http project (a stdio server has nothing to expose).
Options
See Options for the full guide.
| Flag | What it does |
|---|---|
--target <target> | Deploy target to emit artifacts for. Supported: docker, cloudflare, fly. Defaults to docker. |
--out <dir> | Directory to write the artifacts into (default: the project directory itself). |
--force | Overwrite existing artifacts (Dockerfile/.dockerignore) instead of refusing. |
--json | Print a single machine-readable JSON result to stdout instead of human-readable lines. |
klaridian plugins list
List every available observability plugin (id and name)
Options
| Flag | What it does |
|---|---|
--json | Print the list as a single JSON object ({ plugins: [...] }) to stdout instead of aligned text |
klaridian licenses list
List every supported license id for the generated server
Options
| Flag | What it does |
|---|---|
--json | Print the list as a single JSON object ({ licenses: [...] }) to stdout instead of aligned text |