# apigenie-catalog

Source: https://apigenie.pl/docs/reference/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

```sh
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`](/docs/reference/cli/configuration#catalog) 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](/docs/concepts/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 |

```text
$ 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`](https://apigenie.pl/schemas/apigenie-catalog-report.json):

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

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

```text
$ 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](/docs/reference/cli/config) 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](https://semver.org) 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`. |

```text
$ 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`](https://apigenie.pl/schemas/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`. |

```text
$ 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`](https://apigenie.pl/schemas/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](/docs/reference/cli#exit-status)).

## See also

- [Configuration](/docs/reference/cli/configuration#catalog): the `catalog` section.
- [changelog](/docs/reference/cli/changelog): the history of a specification from git.
