crozier

An ultra-fast, memory-efficient OpenAPI-to-SDK code generator written in Rust + minijinja. crozier reproduces Fern's generated SDKs byte-for-byte (with generator-identifying comments aside), driven by nothing but an OpenAPI document and a couple of naming flags — no per-project config, no generators written in the target language.

Python is the only target today; more will follow.

Status: pre-1.0. crozier generates the whole Python SDK — the type layer (pydantic models, enums, unions/aliases), the endpoint clients, the core/ runtime, and the packaging scaffolding — and reproduces Fern's output byte-for-byte across every corpus in its golden suite. See docs/matching.md for how that is verified.

See it in action

One OpenAPI document in, a complete typed Python SDK out — crozier generate writes the whole package in one shot, then you can read the code it produced:

The output is byte-for-byte Fern's. Here is the Pet model crozier emitted from a handful of lines of schema — a real generated file, not a hand-written sample:

crozier generate python takes the document and a couple of naming flags and writes the SDK — the models, enums, the per-endpoint client, and Fern's core/ runtime — into --output:

Or drive one — or several — named generators from a crozier.yml instead of flags. crozier config shows the effective settings for every generator and the layer each value resolved from (CLI flag > CROZIER_* env > file > default):

crozier init drops a starter crozier.yml carrying a JSON Schema modeline, so editors complete and validate it against crozier's own config schema:

A malformed document is rejected at the boundary with an actionable message and a non-zero exit — never a panic:

These are real captures of the CLI, rendered from its actual output by just screenshots and gated by screencomp — change what a command prints and the committed image (and its digest) changes with it.

Install

From PyPI (fastest — a prebuilt binary, no Rust toolchain): crozier ships as platform wheels that wrap the compiled binary and expose it as a console script, so any Python installer puts it on your PATH in seconds:

pip install crozier      # or: pipx install crozier
uvx crozier --help       # run once without installing

Platforms without a prebuilt wheel fall back to the source distribution, which builds from Rust (a toolchain is needed there).

From crates.io:

cargo install crozier --locked

From the install script (prebuilt binary from GitHub Releases, verified):

curl -fsSL https://raw.githubusercontent.com/nickderobertis/crozier/main/scripts/install.sh | sh

It detects your platform, downloads the matching archive, and verifies it against a trust root independent of where it was downloaded — a Sigstore build-provenance attestation when a verifier (cosign, pip install sigstore, or gh) is present, else the canonical SHA-256 checksum. Pin a version or install location with sh -s -- --version v0.1.0 --to ~/.local/bin.

From source (latest main):

cargo install --git https://github.com/nickderobertis/crozier --locked

From a release archive (manual): each release publishes per-platform archives, each with a matching .sha256 and a .sigstore.json provenance bundle. Download the archive for your platform from the Releases page — it lists every target built — verify the checksum (or the attestation), and put the crozier binary on your PATH.

Usage

The fastest path needs no config file — the built-in python generator runs straight from flags:

crozier generate python \
  --spec path/to/openapi.yml \
  --output ./generated \
  --package-name my_api \
  --project-name my-api

• --spec — the OpenAPI 3.x document (.yml, .yaml, or .json).
• --output — directory to write the SDK into.
• --package-name — the Python import package (the directory under src/). Defaults to a snake_case of the API title.
• --project-name — the distribution name recorded in version.py. Defaults to the package name.
• --client-class-name — the name of the generated root client class (Fern's client_class_name). Defaults to {PascalCase(package_name)}Api.
• --audience (repeatable) / --audience-strict — prune generation to x-crozier-audiences.
• --fern-strict — refuse every document in a class Fern refuses (also CROZIER_FERN_STRICT=true, or fern-strict: true in crozier.yml). A refusal exits 1, writes nothing, and names the refusal class and the offending element. Each class Fern refuses is decided once, in docs/fern-refusals/: refuse, where crozier refuses the document whatever this setting says, or generate, where it writes a valid SDK by default and refuses only under --fern-strict. Every class registered today is refuse, so the flag changes no outcome yet.

crozier exits 0 on success (with a one-line summary on stderr), 1 on an error, printing the exact problem and a suggested fix, and 2 on a usage error (a bad flag or argument). crozier compare adds 3 and 4 for its results (docs/compare.md).

To check crozier against the SDK you generate today, before switching, run crozier compare: for every generator your crozier.yml files declare, it runs a reference command you configure, generates crozier's SDK, compares the two trees with comments set aside and crozier's intended departures — its own identity headers, a corrected Fern defect, and the rest — reported line by line rather than failed, and reports the time each side took. See docs/compare.md. Moving from Fern, the Fern reference recipe produces that reference.

In CI, the GitHub Action runs the same check on every pull request and reports it in the job summary:

      - uses: nickderobertis/crozier@v0

See docs/github-action.md for its inputs, outputs and versioning, and the one workflow a repository migrating from Fern adds.

Configuration

crozier runs one or more named generators. You can drive them purely from flags (above), from a crozier.yml, or any mix — every setting resolves per field as:

CLI flag  >  CROZIER_* env var  >  crozier.yml (generator over shared)  >  built-in default

Run crozier init to drop a starter crozier.yml in the working directory. It leads with a JSON Schema modeline —

# yaml-language-server: $schema=https://raw.githubusercontent.com/nickderobertis/crozier/main/assets/crozier.schema.json

— so editors with the YAML language server give field completion and validation against the published schema (derived from crozier's own config types, so it never drifts). Run crozier config to print the effective settings and the layer each value came from.

A crozier.yml in the working directory is picked up automatically. Top-level keys are shared defaults; each entry under generators: is one SDK to emit:

# Shared across every generator
spec: ./openapi.yml
audiences: [public]

generators:
  python:              # overrides the built-in `python` generator
    output: ./sdks/python
    package-name: my_api
    project-name: my-api
  admin:               # a second generator (also Python for now)
    type: python
    spec: ./admin-openapi.yml
    output: ./sdks/admin
    package-name: admin_api

• crozier or crozier generate — run every configured generator (or the built-in python when nothing is configured).
• crozier generate <name> — run one generator by name (python always works, even with no config file).
• crozier init — write a starter crozier.yml (--output, --force).
• crozier config [<name>] — show the effective config and each value's source.
• crozier schema — print the config JSON Schema to stdout.
• --config <path> (repeatable, later wins) selects config files instead of auto-discovery; --no-config ignores config files entirely; CROZIER_CONFIG names a file via the environment.

Per-generation flags (--spec, --output, …) apply to a single generator, so they are rejected when more than one would run — name one, or set the values in crozier.yml. See docs/configuration.md for the full reference.

Migrating from Fern

A repository can move from Fern's Python generator to crozier one generator at a time, checking each against Fern before it switches. Before step 1, bring the Fern generator to the version crozier certifies; that and the other steps a migration may still need are in docs/migrating-from-fern.md.

1. Add crozier config beside the Fern config, one generator at a time. Save your copy of the Fern reference recipe and name it as reference.command. Set layout to how that generator's Fern output was written: flat for a local-file-system output path (point output where that tree lives), packaged (the default) for fern generate --preview --output:

# crozier.yml, at the repository root beside fern/
generators:
  python:
    spec: ./fern/openapi/openapi.yml
    output: ./sdks/python          # the generator's local-file-system path
    package-name: acme             # fern.config.json's organization
    layout: flat
    reference:
      command: ./scripts/fern-reference.sh

2. Compare until every generator matches, locally and in CI with the GitHub Action:

crozier compare

It checks only generators that have crozier config, so the ones still on Fern do not fail it. crozier does not track what is left; list the Python generators your Fern config still runs:

grep -rn --include=generators.yml 'fernapi/fern-python-sdk' .

docs/compare.md covers the report, exit statuses, JSON report, timings and the reference-command contract.

3. Switch the build from fern generate to crozier:

crozier generate python

4. Remove that generator (its fernapi/fern-python-sdk entry) from generators.yml. TypeScript and other generators stay on Fern.

Development

The command surface is a small set of just recipes:

just bootstrap   # set up from a clean clone (toolchain + dev tools)
just check       # full gate — must pass before any commit or PR
just test        # fast tests with coverage enforced (95%)
just test-e2e    # drive the compiled binary and byte-compare against fixtures
just format      # rustfmt in place
just upgrade     # cargo update, then re-run the gate

Bootstrap enables the repository hooks (the .githooks/pre-push visual-regression guard). The tracked .cargo/config.toml is the build contract: every cargo invocation inside a clone builds into that clone's own target/ (two worktrees never share one), and dev/test builds keep line tables only (debug = 1) so full debuginfo stays off the disk. Nothing in the tree configures sccache; to share compiler results across worktrees, set [build] rustc-wrapper = "sccache" in your user-level ~/.cargo/config.toml, which Cargo merges with the repository's.

See AGENTS.md for the durable contributor guide and docs/matching.md for the byte-matching strategy.

License and attribution

crozier is licensed under Apache-2.0. It is an independent, clean-room implementation — it reproduces Fern's generated output format (the project's explicit goal) and does not copy Fern's generator source.

The test fixtures under tests/fixtures/ are Fern's own output and OpenAPI test specs, used under Apache-2.0 with attribution and a statement of changes; see NOTICE and licenses/fern-APACHE-2.0.txt.