grapity materialize

Fetch registered specs from the Grapity Registry into the current repository.

Usage

grapity materialize [name] [options]

Description

grapity materialize resolves specs through the existing CLI auth and writes them into the current repository. It pins the exact resolved version in grapity.yaml, records resolved/latest metadata in grapity-lock.json, and warns when the pinned version is no longer the latest registry version.

This command does not generate code. Use your existing language tooling (for example openapi-typescript, openapi-generator, or oapi-codegen) with the materialized spec files.

Arguments

Argument	Description
[name]	Name of the spec to materialize. Omit to materialize every spec declared in grapity.yaml.

Options

Option	Description	Default
--semver <semver>	Specific version to materialize	Value from grapity.yaml, or latest
--output <path>	Destination path for the spec file	Value from grapity.yaml, or ./grapity/specs/<name>.yaml
--format <format>	Output format: yaml or json	Value from grapity.yaml, or yaml
--force	Overwrite an existing file even if it differs	false
--fail-on-stale	Exit with an error when the resolved version is not the latest	false
--config <path>	Path to grapity.yaml	./grapity.yaml
--check	Verify lockfile specs are still the latest registry versions	false
--json	With --check, print results as JSON for CI consumption	false

Configuration file

grapity.yaml declares which specs the repository consumes. It is created automatically on first materialize and can be edited by hand.

version: "1"

specs:
  - name: payments-api
    semver: 1.2.0
    output: ./grapity/specs/payments-api.yaml
    format: yaml

  - name: users-api
    # omit semver to track latest; the CLI writes the resolved version back

Examples

Materialize a single spec with a pinned version

grapity materialize payments-api --semver 1.2.0

Materialize every spec declared in grapity.yaml

grapity materialize

Generate TypeScript types from the materialized spec

grapity materialize payments-api
npx openapi-typescript ./grapity/specs/payments-api.yaml --output ./src/generated/payments-api.ts

Check all specs for newer registry versions

grapity materialize --check

Fail CI when any spec is stale

grapity materialize --check --fail-on-stale

JSON output for CI pipelines

grapity materialize --check --json

Prints a machine-readable summary:

{
  "stale": true,
  "specs": [
    { "name": "payments-api", "resolved": "1.2.0", "latest": "1.3.0", "stale": true },
    { "name": "users-api", "resolved": "2.0.0", "latest": "2.0.0", "stale": false }
  ]
}

When the GITHUB_ACTIONS environment variable is set, --check additionally emits ::warning:: annotations for stale specs, so drift appears inline in the GitHub checks UI.

CI integration

A ready-to-copy GitHub Actions workflow that runs the check on every pull request and reports drift as a sticky PR comment lives in the grapity repository at examples/consumer/. It calls the grapitydev/grapity/actions/grapity composite action with command: check, which wraps --check --json, and warns by default (fail-on-stale: "true" makes it blocking).

Lockfile

Every successful materialize writes ./grapity-lock.json:

{
  "version": "1",
  "specs": {
    "payments-api": {
      "requested": "1.2.0",
      "resolved": "1.2.0",
      "latest": "1.3.0",
      "stale": true,
      "fetchedAt": "2026-06-20T12:00:00Z"
    }
  }
}

Stale-version warnings

When the resolved version is not the latest registry version, a warning is printed to stderr. Use --fail-on-stale to make the command exit non-zero.

See also

• grapity init — Configure the CLI
• grapity registry push — Publish a spec to the registry
• grapity serve — Start the Registry server