CLI reference

The okapipy command is a Typer application with two sub-apps: nlp and spec. Run okapipy --help (or any subcommand with --help) for the canonical, version-pinned usage; this page is a human-readable summary.

okapipy [-v | -vv] {nlp | spec} ...

The top-level -v / -vv flag controls log verbosity (INFO / DEBUG). Without it, only WARNING and above reach stderr.

---

okapipy nlp

Manage local spaCy NLP models.

okapipy nlp fetch

Download and install the spaCy model for a language into a local cache.

okapipy nlp fetch <LANG> [--cache-dir DIR]

Argument / option	Default	Description
LANG	required	ISO language code (e.g. en, es, fr).
--cache-dir	./.spacy	Directory in which to store the downloaded model.

The cache directory persists across runs; subsequent invocations are no-ops if the model is already present at the right version. Useful in CI before any other okapipy command, so the first parse doesn't pay the network cost.

fetch_model

fetch_model(lang: str, cache_dir: Path = DEFAULT_CACHE_DIR) -> Path

Download the spaCy model for lang into cache_dir and return its path.

Uses spaCy's own download command, passing --target so the package is laid out under cache_dir/<model_name>/... instead of being installed globally.

Raises:

Type	Description
NlpModelMissingError	When the download fails for any reason (network down, unknown model name, pip failure).

---

okapipy spec

Inspect and parse OpenAPI specifications, and generate clients from them.

okapipy spec parse

Parse an OpenAPI document and either print the resulting structural tree as JSON to stdout, or save it to a file.

okapipy spec parse <SOURCE> [OPTIONS]

Argument / option	Default	Description
SOURCE	required	Path or http(s) URL of the OpenAPI document.
--rules PATH	none	Local path to a JSON/YAML rules file.
--lang CODE	en	ISO language code for NLP.
--strip-prefix STRING	None	Path prefix to strip from every path before classification (e.g. /public/v1). Overrides the prefix inferred from servers[].url.
--nlp-cache-dir DIR	./.spacy	Where to look for / store the spaCy model.
--unmatched NAME	none	Bulk escape hatch: keep operations that would otherwise be dropped by the routing table as flat actions under a top-level namespace called NAME. Each action is named after its operationId, falling back to <method>_<path> when no operationId is declared. NAME must not collide with any existing top-level node. See Rules and extensions.
--output PATH	none	Write the parsed tree to a file. Format inferred from .json / .yaml / .yml extension.

Output:

• stderr — a counts panel (namespaces / collections / resources / actions) and any non-fatal warnings.
• stdout — JSON dump of the parsed tree, syntax-highlighted on a TTY, plain when piped.

Exit codes:

• 0 — parse succeeded.
• 1 — parser raised; the error message is printed to stderr.

okapipy spec generate

Generate a Python client project from an OpenAPI document.

okapipy spec generate <SOURCE> --output DIR --package PKG --client-class NAME [OPTIONS]

Required:

Option	Description
--output DIR, -o DIR	Directory to write the generated project into.
--package PKG	Dotted Python package path (e.g. acme.commerce).
--client-class NAME	PascalCase class name for the sync client. The async sibling is Async<name>.

Project metadata:

Option	Default	Description
--project-name NAME	last segment of --package	PEP 503 distribution name.
--project-version V	0.1.0	Initial version string emitted into pyproject.toml.
--python-version V	3.13	Pinned Python version for the generated project.
--license SPDX	Proprietary	SPDX license identifier. Recognised values (MIT, Apache-2.0, BSD-3-Clause, BSD-2-Clause, MPL-2.0) emit the full license text into LICENSE and the license field in pyproject.toml; any other value emits a TODO placeholder and omits the license field.
--author NAME	none	Copyright holder. When set, written into the LICENSE copyright line and as a PEP 621 authors = [{ name = "NAME" }] entry in pyproject.toml. When unset, LICENSE falls back to the project name and pyproject.toml omits the authors block.

Parser options (forwarded to okapipy spec parse):

Option	Default	Description
--rules PATH	none	Local path to a JSON/YAML rules file.
--lang CODE	en	ISO language code for NLP.
--strip-prefix STRING	None	Path prefix to strip before classification.
--nlp-cache-dir DIR	./.spacy	spaCy model cache.
--unmatched NAME	none	Bulk escape hatch for operations that don't fit the routing table. See spec parse above and the worked example.

Generator options:

Option	Default	Description
--templates-dir DIR	none	User Jinja templates that override the packaged defaults. See Template customization.
--model-templates-dir DIR	none	datamodel-code-generator templates for models.py.
--shape {models\|dicts}	unset (dual shape)	Lock the generated client to a single response shape. Omit to produce a dual-shape client (shape= constructor + with_shape()). --shape dicts also skips base/models.py. See Response shape.
--check	off	Dry-run; report drift, exit non-zero on any change. CI gate.
--quiet, -q	off	Suppress drift-detection warnings. Pruning still runs.

Output:

• stderr — a green summary panel naming the output directory and the file count (Wrote 35 files to ./my-client). When the parser emitted any warnings during the run, the panel appends ; N warning(s) emitted so the count is visible even if individual warnings scrolled past in the terminal.

Exit codes:

• 0 — generated successfully (or --check passed with no drift).
• 1 — parse error, generator error, or --check found drift.