apigenie-catalog
apigenie-catalog lists the API specifications of a repository, records their names and owners
in the configuration file, and releases them as Git tags. It is installed next to apigenie by
every archive and package, npm and Homebrew; apigenie catalog ... prints the apigenie-catalog
command to run instead.
(experimental, outside the 1.0 compatibility promise)
apigenie-catalogis the first part of a catalog kept in Git: pinned consumers and a catalog spanning several repositories will add options and settings.
Usage
apigenie-catalog list [DIR] [--json] [--config FILE | --no-config] [--git PROGRAM]
apigenie-catalog init [DIR] [--prune] [--dry-run] [--config FILE] [--git PROGRAM]
apigenie-catalog versions NAME [--json] [--config FILE | --no-config] [--git PROGRAM]
apigenie-catalog release NAME VERSION [--dry-run] [--push] [--remote REMOTE] [--message MESSAGE] [--json] [--config FILE] [--git PROGRAM]
apigenie-catalog --version | --credits | --license [LIBRARY] | --license-list
Description
The repository that holds your specifications is the catalog: nothing is uploaded anywhere.
apigenie-catalog list works in any repository without configuration. apigenie-catalog init
writes a catalog section in apigenie.yaml for
what can’t be derived from the specifications, such as a name that stays when a file moves, an
owner and a lifecycle. A release of a specification is a Git tag: apigenie-catalog release
creates it and apigenie-catalog versions lists them.
What is a specification
apigenie-catalog list looks at the files below DIR (the current directory by default):
- in a Git repository, the files Git tracks or would track: committed and staged files, and new
files that no ignore rule (
.gitignore,.git/info/exclude, your global excludes file) excludes; - outside git, every file except those in directories whose name starts with a dot, and in
node_modules.
Files matching a pattern of catalog.exclude are left out. Of the others, these are
specifications:
| Format | Files |
|---|---|
| OpenAPI, AsyncAPI, Swagger | JSON and YAML files whose root has the openapi, asyncapi or swagger property |
| Protobuf | every .proto file |
| GraphQL | .graphql, .graphqls and .gql files with type definitions (operation documents are left out) |
The files of a split document that only hold components have no openapi property, so only its
root file is listed. Files that can’t be read are reported on the standard error.
What the catalog counts as a specification
explains these rules, the names and the root with a repository to try them on.
What is listed
| Column | JSON | Value |
|---|---|---|
| NAME | name |
the name given in the catalog section, else derived: info.title (Orders API is orders-api), the Protobuf package (acme.pricing.v1 is acme-pricing-v1), or the file name (GraphQL) |
| FORMAT | format, specVersion |
the format and its version: OpenAPI 3.1.0, Protobuf proto3, GraphQL |
| VERSION | version |
info.version |
| OWNER | owner |
the owner given in the catalog section; the column is shown when any specification has one |
| LIFECYCLE | lifecycle, sunset |
the lifecycle given in the catalog section, with the sunset day in parentheses when one is given: deprecated (2027-03-31). When none is given, the table shows active and the JSON null. The column is shown when any specification has a lifecycle (since 0.12.0) |
| PATH | path |
the file, relative to the root of the catalog |
| COMMIT | commit |
the last commit changing the file (short id and day); - for a file not committed yet and outside git |
$ apigenie-catalog list
NAME FORMAT VERSION PATH COMMIT
order-events AsyncAPI 3.0.0 2.0.0 apis/events.json 96175d8 2026-10-12
orders-api OpenAPI 3.1.0 1.2.0 apis/orders/openapi.yaml 4d0c2e1 2026-10-14
schema GraphQL - graphql/schema.graphql 96175d8 2026-10-12
acme-pricing-v1 Protobuf proto3 - proto/pricing.proto 96175d8 2026-10-12
Two specifications with the same derived name are reported on the standard error; name them in
the catalog section, which apigenie-catalog init does.
The root of the catalog is the directory of the configuration file (the one given with
--config, else apigenie.yaml found in DIR or a parent up to the root of the repository), else
the root of the Git repository, else DIR. Paths are relative to it, in the output and in the
catalog section. DIR only narrows the search and must be inside the root.
versions and release take no DIR: they read the catalog of the current directory, found as
list finds it, and need a Git repository.
apigenie-catalog list
| Option | Description |
|---|---|
DIR |
The directory to look for specifications in. Defaults to the current directory. |
--json |
Prints the catalog as JSON (see below). |
--config FILE |
Uses FILE instead of the configuration file found in the repository. |
--no-config |
Uses no configuration file: no names, owners or exclusions. |
--git PROGRAM |
The git program. Defaults to git. |
With --json, the output follows
apigenie-catalog-report.json:
{
"formatVersion": 1,
"root": "/home/me/specs",
"config": "/home/me/specs/apigenie.yaml",
"git": true,
"specs": [
{
"name": "orders-api",
"title": "Orders API",
"format": "openapi",
"specVersion": "3.1.0",
"version": "1.2.0",
"path": "apis/orders/openapi.yaml",
"owner": "team-commerce",
"lifecycle": null,
"sunset": null,
"listed": true,
"commit": {
"id": "4d0c2e1f…",
"shortId": "4d0c2e1",
"author": "Jane Doe",
"date": "2026-10-14T09:12:00+02:00",
"subject": "Add order cancellation"
}
}
],
"warnings": []
}
listed tells whether the catalog section lists the file.
apigenie-catalog init
Writes the catalog section of the configuration file from what apigenie-catalog list finds:
one entry per specification with its name, its path and owner: null, for you to fill in.
catalog:
specs:
- name: order-events
path: apis/events.json
owner: null
- name: orders-api
path: apis/orders/openapi.yaml
owner: null
- Without a configuration file, it creates
apigenie.yamlat the root of the repository (or the file given with--config). - In an existing file, it appends the section, or replaces the lines of the section, and leaves
the rest of the file as it is. A section written in flow style (
catalog: {...}) and JSON files are rewritten whole; comments are kept. - Run it again after adding specifications: new ones are added, the entries you edited stay as
they are, and entries whose files are gone are reported as “not found”.
--pruneremoves them. - Names that two specifications would share get a number:
orders-api-2.
| Option | Description |
|---|---|
DIR |
The directory to look for specifications in. Defaults to the current directory. |
--prune |
Removes the entries whose files are gone. |
--dry-run |
Prints the configuration file instead of writing it. |
--config FILE |
Writes FILE instead of the configuration file found in the repository; it is created if missing. |
--git PROGRAM |
The git program. Defaults to git. |
$ apigenie-catalog init
Updated /home/me/specs/apigenie.yaml: 2 added, 4 kept, 1 not found
added apis/billing.yaml
added apis/orders-v2.yaml
not found legacy/swagger.yaml
Remove the entries of the files that are gone with --prune.
The file is checked against the configuration schema before it
is written, and apigenie config check accepts it.
apigenie-catalog versions
Since 0.12.0, lists the releases of a specification: the Git tags that match
catalog.tags.pattern ({name}-{version} by default) for its name and hold a
semantic version where {version} stands, newest first. A tag that holds
anything else there (orders-api-next) is not a release. Tags on commits that HEAD doesn’t
contain, such as on a maintenance branch, are releases too. Tags made with another pattern are
not: after a change of tags.pattern, versions doesn’t list them and release doesn’t check
against them.
| Option | Description |
|---|---|
NAME |
The name of the specification, as list prints it. |
--json |
Prints the releases as JSON (see below). |
--config FILE |
Uses FILE instead of the configuration file found in the repository. |
--no-config |
Uses no configuration file: derived names and the default tag pattern. |
--git PROGRAM |
The git program. Defaults to git. |
$ apigenie-catalog versions orders-api
VERSION TAG COMMIT
1.1.0-rc.1 orders-api-1.1.0-rc.1 c121c1b 2026-10-28
1.0.0 orders-api-1.0.0 12e9f3d 2026-10-12
apis/orders/openapi.yaml is at info.version 1.1.0, which is not released
The last line appears when no release holds the file’s info.version: the version about to be
released, or a forgotten tag. Without a release the command prints No releases of orders-api: no tag matches orders-api-* and exits with status 0.
With --json, the output follows
apigenie-catalog-versions-report.json:
name, path, tagPattern, the file’s version and whether it is unreleased, and
releases (version, tag, commit), newest first.
apigenie-catalog release
Since 0.12.0, releases a specification: creates the annotated tag that catalog.tags.pattern
names for NAME and VERSION at HEAD. It refuses, with every problem on the standard error and exit
status 2, when:
- VERSION is not a semantic version (
MAJOR.MINOR.PATCH, with an optional pre-release such as1.4.0-rc.1; nov, no build metadata); - VERSION is released already, or below the latest release (a patch of an older line, such as 1.0.1 after 1.1.0, is tagged by hand);
- the tag exists;
- the file has changes that are not committed (staged or not, or the file is untracked);
- the document has an
info.version(OpenAPI, AsyncAPI, Swagger) and it is not VERSION. A Protobuf file or GraphQL schema has no version field, so its tag is its version; - the catalog section marks the specification
retired.
Nothing is pushed unless --push is given; the command prints the git push to run otherwise.
When the push fails (no such remote, no access), the tag stays in the local repository: the
command says so, prints the git push to run, and exits with status 2.
| Option | Description |
|---|---|
NAME |
The name of the specification, as list prints it. |
VERSION |
The version to release. |
--dry-run |
Runs the checks and prints the tag that would be created, without creating it. |
--push |
Pushes the tag to the remote after creating it. |
--remote REMOTE |
The remote --push pushes to. Defaults to origin. |
--message MESSAGE |
The message of the annotated tag. Defaults to NAME VERSION. |
--json |
Prints the release as JSON (see below), also when problems stop it. |
--config FILE |
Uses FILE instead of the configuration file found in the repository. |
--git PROGRAM |
The git program. Defaults to git. |
$ apigenie-catalog release orders-api 1.1.0
Tagged orders-api-1.1.0 at b2e21b5 Release 1.1.0 of the Orders API (previous release: 1.1.0-rc.1, tag orders-api-1.1.0-rc.1)
Push it with: git push origin orders-api-1.1.0
$ apigenie-catalog release orders-api 1.1.0
1.1.0 is released already, as tag orders-api-1.1.0 at b2e21b5
orders-api 1.1.0 is not released
The lines of a refusal go to the standard error. With --json, the output follows
apigenie-catalog-release-report.json:
the tag, the commit, the previous release, whether the tag was created and pushed, the
remote given with --push (else null), and the problems that stopped the release.
The release of a specification is the tag, so apigenie changelog lists the changes between two
releases with --from orders-api-1.0.0 --to orders-api-1.1.0, and apigenie diff compares the
files that git show orders-api-1.0.0:apis/orders/openapi.yaml writes.
Exit status
| Status | Meaning |
|---|---|
| 0 | Success, also when files can’t be read or specifications other than NAME share a name (reported on the standard error). |
| 2 | The directory doesn’t exist or is outside the root of the catalog, the configuration file is invalid, git fails, versions or release runs outside a Git repository, no specification or several have the NAME, a release is refused, --push fails (the tag stays in the local repository), an unknown --license library, or a usage error. |
These are the statuses of every command (exit status).
See also
- Configuration: the
catalogsection. - changelog: the history of a specification from git.