API Genie

apigenie-catalog lists the API specifications of a repository, and records their names and owners in the configuration file. 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: release tags, 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 --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 and an owner.

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 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
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.

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",
      "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.

Exit status

Status	Meaning
0	Success, also when files can’t be read or names are shared (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, an unknown `--license` library, or a usage error.

These are the statuses of every command (exit status).

catalog