grapity registry
Manage specs in the Grapity Registry.
Usage
grapity registry <command> [options]Description
Use grapity registry to publish, validate, inspect, and delete API specs in the Grapity Registry.
Commands
| Command | Description |
|---|---|
push <file> | Push a spec to the Registry |
validate <file> | Validate a spec without storing it |
list | List all specs |
get <name> | Get spec metadata and latest version |
update <name> | Update spec metadata (visibility) |
versions <name> | List all versions of a spec |
spec <name> | Fetch the raw spec document |
delete <name> | Delete a spec and all its versions |
grapity registry push
Push a spec file to the Registry. Validates structure, checks backward compatibility, assigns a semver, and stores the result.
Pushes are idempotent: if the content is identical to the latest version, the Registry registers nothing and reports no changes with the current version. A --visibility change supplied in the same push still applies without creating a version.
Usage
grapity registry push <file> --name <name> [options]Arguments
| Argument | Description |
|---|---|
<file> | Path to the OpenAPI spec file |
Options
| Option | Description | Default |
|---|---|---|
--name <name> | Required. Spec name (URL-friendly identifier) | — |
--type <type> | Spec type: openapi | openapi |
--description <desc> | Description of the spec | — |
--owner <owner> | Owner team or individual | — |
--source-repo <url> | Source repository URL | — |
--tags <tags> | Comma-separated tags | — |
--visibility <visibility> | Spec visibility: private (authenticated reads only) or public (anonymous reads allowed). On an existing spec, supplying it updates visibility; omitting it leaves it unchanged | private on first push |
--git-ref <ref> | Git commit SHA | — |
--pushed-by <by> | Pusher identity (user or CI) | — |
--force | Force push even with breaking changes | false |
--reason <reason> | Reason for force push (required with --force) | — |
--prerelease | Push as pre-release version (0.x) | false |
Examples
Push a new spec:
grapity registry push ./openapi.yaml --name payments-apiPush with metadata:
grapity registry push ./openapi.yaml --name payments-api \
--description "Payments API v2" \
--owner platform-team \
--tags payments,public \
--git-ref abc1234Force push a breaking change:
grapity registry push ./openapi.yaml --name payments-api \
--force --reason "security fix CVE-2026-1234"grapity registry validate
Validate a spec against the latest version in the Registry without storing anything. When the content is identical to the latest version, the result reports unchanged and the CLI prints No changes detected, matching what an idempotent push would do.
Usage
grapity registry validate <file> --against <name>Options
| Option | Description | Default |
|---|---|---|
--against <name> | Required. Spec name to validate against | — |
Example
grapity registry validate ./openapi.yaml --against payments-apiOutput shows whether the spec is valid and lists any breaking or safe changes. When no spec exists for --against yet, the content is validated structurally and reported as an initial version, mirroring what a first push would accept.
The command exits 1 when the spec is invalid or contains blocked breaking changes, so it can gate CI jobs. Sunset-eligible removals still exit 0.
grapity registry list
List all specs in the Registry.
Usage
grapity registry list [options]Options
| Option | Description | Default |
|---|---|---|
--type <type> | Filter by spec type: openapi | — |
--owner <owner> | Filter by owner | — |
--tags <tags> | Comma-separated tag filter | — |
Example
grapity registry list --type openapi --owner platform-teamgrapity registry get
Get metadata and latest version details for a spec.
Usage
grapity registry get <name>Example
grapity registry get payments-apigrapity registry update
Update mutable spec metadata without creating a new version. Currently supports changing visibility to publish or unpublish anonymous read access.
Usage
grapity registry update <name> --visibility <visibility>Options
| Option | Description | Default |
|---|---|---|
--visibility <visibility> | Required. New visibility: private or public | — |
Examples
Publish a spec so anyone can read it without a token:
grapity registry update payments-api --visibility publicMake it private again:
grapity registry update payments-api --visibility privategrapity registry versions
List all versions of a spec, newest first.
Usage
grapity registry versions <name> [options]Options
| Option | Description | Default |
|---|---|---|
--limit <n> | Maximum versions to return (max 25) | 10 |
--offset <n> | Number of versions to skip | 0 |
Example
grapity registry versions payments-api --limit 5grapity registry spec
Fetch the raw spec document for an API. Prints to stdout, pipe-friendly.
Usage
grapity registry spec <name> [options]Options
| Option | Description | Default |
|---|---|---|
--semver <semver> | Specific version | latest |
--format <format> | Output format: json or yaml | yaml |
Examples
Latest version as YAML:
grapity registry spec payments-apiLatest as JSON:
grapity registry spec payments-api --format jsonSpecific version:
grapity registry spec payments-api --semver 1.2.0Pipe to another tool:
grapity registry spec payments-api | yq '.info.title'grapity registry delete
Delete a spec and all its versions from the registry.
Usage
grapity registry delete <name> [options]Options
| Option | Description | Default |
|---|---|---|
-f, --force | Skip confirmation prompt | false |
Example
grapity registry delete payments-apiSee also
- grapity init — Configure the CLI
- grapity materialize — Fetch a registered spec into the current repository
- grapity serve — Start the Registry server