# catalog

Source: https://apigenie.pl/techdocs/reference/cli-catalog

`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

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

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

### 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",
      "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](/techdocs/reference/cli-config) 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](/techdocs/reference/cli-overview#exit-status)).

## See also

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