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-catalog is 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.yaml at 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”. --prune removes 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 as 1.4.0-rc.1; no v, 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

Was this helpful?