# apigenie

Source: https://apigenie.pl/docs/reference/cli
See also: [bundle](https://apigenie.pl/docs/reference/cli/bundle.md), [changelog](https://apigenie.pl/docs/reference/cli/changelog.md), [config](https://apigenie.pl/docs/reference/cli/config.md), [convert](https://apigenie.pl/docs/reference/cli/convert.md), [credits](https://apigenie.pl/docs/reference/cli/credits.md), [diff](https://apigenie.pl/docs/reference/cli/diff.md), [evolve](https://apigenie.pl/docs/reference/cli/evolve.md), [format](https://apigenie.pl/docs/reference/cli/format.md), [i18n](https://apigenie.pl/docs/reference/cli/i18n.md), [init](https://apigenie.pl/docs/reference/cli/init.md), [license](https://apigenie.pl/docs/reference/cli/license.md), [lint](https://apigenie.pl/docs/reference/cli/lint.md), [overlay](https://apigenie.pl/docs/reference/cli/overlay.md), [test](https://apigenie.pl/docs/reference/cli/test.md).

`apigenie` is the API Genie command-line interface. Each command works on one or more API
descriptions: OpenAPI, Swagger 2.0, AsyncAPI, Protobuf or GraphQL files, in JSON or YAML. Code
generation, the mock server, the API catalog and the MCP server are separate executables installed
next to it: [`apigenie-generator`](/docs/reference/generator),
[`apigenie-server`](/docs/reference/server), [`apigenie-catalog`](/docs/reference/catalog) and
[`apigenie-mcp`](/docs/reference/cli/mcp).

From 1.0.0 the commands, options, configuration keys, exit statuses and JSON outputs follow
semantic versioning; [Compatibility](/docs/reference/cli/compatibility) says what that covers.
The site is built from the development version, so a page can describe what the last release
does not have yet; that is marked with the version that brings it, "since 0.11.0".

## Usage

```sh
apigenie COMMAND [OPTIONS] [FILES]
```

## Commands

| Command | What it does |
| ------- | ------------ |
| [`apigenie bundle`](/docs/reference/cli/bundle) | Combines an OpenAPI, Swagger 2.0 or AsyncAPI document, or a Protobuf file, and the files it references into one file |
| [`apigenie changelog`](/docs/reference/cli/changelog) | Builds the changelog of an OpenAPI, Swagger 2.0, AsyncAPI, Protobuf or GraphQL file from its Git history |
| [`apigenie config`](/docs/reference/cli/config) | Prints the configuration in effect, checks a configuration file and prints its JSON Schema |
| [`apigenie convert`](/docs/reference/cli/convert) | Converts Swagger 2.0 to OpenAPI 3.2, WSDL 1.1 to OpenAPI 3.1, and JSON Schema 2019-09 or 2020-12 to draft-07, draft-04 or the OpenAPI 3.0 dialect (experimental) |
| [`apigenie credits`](/docs/reference/cli/credits) | Lists the third-party libraries API Genie uses, with their licenses |
| [`apigenie diff`](/docs/reference/cli/diff) | Compares two versions of an OpenAPI, Swagger 2.0 or AsyncAPI document, or of a Protobuf or GraphQL file, and rates each change by what it does to clients |
| [`apigenie evolve`](/docs/reference/cli/evolve) | Splits a breaking OpenAPI change into an expand wave and a contract wave (experimental) |
| [`apigenie format`](/docs/reference/cli/format) | Puts OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files in one style |
| [`apigenie i18n`](/docs/reference/cli/i18n) | Extracts the texts of OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files for translation, and applies translations |
| [`apigenie init`](/docs/reference/cli/init) | Sets a repository up: `apigenie.yaml` with the lint rules of the API descriptions found, and the section of `AGENTS.md` for coding agents |
| [`apigenie license`](/docs/reference/cli/license) | Prints the license of API Genie and of the libraries it uses |
| [`apigenie lint`](/docs/reference/cli/lint) | Checks OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files against the [rules](/docs/linter) of their standard |
| [`apigenie overlay`](/docs/reference/cli/overlay) | Applies OpenAPI Overlays to an OpenAPI document |
| [`apigenie test`](/docs/reference/cli/test) | Runs the requests of `.http` files (HTTP, gRPC, WebSocket, MQTT) and generated requests against a live API, and checks them against its OpenAPI or AsyncAPI document or `.proto` file |

Commands marked *experimental* are outside the
[1.0 compatibility promise](/docs/reference/cli/compatibility); see
[Experimental commands](#experimental-commands).

## The five binaries

API Genie installs five executables side by side, always of the same version:

| Binary | What it does |
| ------ | ------------ |
| `apigenie` | Lints, formats, compares, bundles, converts and tests API documents (the commands above) |
| [`apigenie-generator`](/docs/reference/generator) | Generates clients, servers, documentation, data and validation schemas from OpenAPI, Swagger, AsyncAPI and JSON Schema documents |
| [`apigenie-server`](/docs/reference/server) | Serves a document as a mock server, or proxies a live API and checks the traffic against the contract |
| [`apigenie-catalog`](/docs/reference/catalog) | Lists the API specifications of a repository and keeps their names and owners in `apigenie.yaml` (experimental) |
| [`apigenie-mcp`](/docs/reference/cli/mcp) | Serves the checks of `apigenie` to coding agents as tools of the Model Context Protocol (experimental) |

The `--help` of each one ends with a line naming the others. `apigenie --version` prints the
version on its first line and, below it, the versions of `apigenie-generator`, `apigenie-server`,
`apigenie-catalog` and `apigenie-mcp` when they are installed next to it; scripts that compare the version should read the first line:

```sh
apigenie --version | head -n 1
```

Code generation was `apigenie generate` before 0.9.0: `apigenie generate ...` and `apigenie mock
...` now exit with status 2 and print the command to run instead, e.g. `run: apigenie-generator
client fetch api.yaml -o client`, and so does `apigenie catalog ...`, which points to
`apigenie-catalog`.

## Exit status

The five binaries share one table of exit statuses. The
[1.0 compatibility promise](/docs/reference/cli/compatibility) freezes it: scripts and CI
jobs can rely on these numbers.

| Status | Meaning |
| ------ | ------- |
| 0 | Success |
| 1 | Findings: `lint` found errors, `diff` found breaking changes, `format --check` found files to reformat, `i18n apply --strict` found unknown keys, `overlay --validate` found problems in an overlay, `apigenie-generator --check` found generated files that would be created or changed |
| 2 | A usage, input or unexpected error: bad or unknown options, an unknown command, a file that can't be read or isn't a valid document, a bad configuration file, or an internal error |
| 3 | `apigenie-server`: the document can't be served |
| 4 | `apigenie-server`: the address can't be used (the port is taken, ...) |
| 5 | The contract or replay report failed: `apigenie-server` with `--fail-on` or `--min-coverage`, or with `--replay` when a recorded exchange was never replayed or a request matched none; `apigenie test` when a request or the contract gate failed |

`apigenie-server` also exits with 130 when a second Ctrl+C stops it at once, as shells do for a
process interrupted by a signal. An unknown command or subcommand prints the help of the command
above it on the standard error. In 0.9 and earlier, errors exited with 255 or 1 depending on the
command; see the Upgrading section of the changelog.

## JSON output

Since 0.12.0, every command takes `--json`: the standard output then holds one JSON document and
nothing else, for scripts and coding agents. Commands with a report print it: `lint`, `diff` and
`changelog` the same report as `--formatter json`, `format` the files and whether each changed,
`test` its test report, `evolve plan` and `i18n check` their reports, `config` the effective
configuration, `apigenie-catalog list` the catalog. The other commands print the status of the run:

```sh
apigenie config check --json missing.yaml
```

```json
{
  "formatVersion": 1,
  "command": "apigenie config check",
  "exitStatus": 2,
  "messages": [
    "No such file: missing.yaml"
  ]
}
```

`output` holds what the command would have printed without `--json`, such as the document
`apigenie convert` writes to the standard output. A command line that can't be parsed prints the
status too. `--json` may also come before the subcommand (`apigenie i18n --json check`), and it
changes only the standard output: `changelog --output` still writes the file with the formatter
asked for, and prints the status. `--help` prints the help as text. The exit status is the same as
without `--json`, and the messages are still printed on the standard error. The JSON document is
UTF-8: text that isn't (a path, say) gets U+FFFD for each ill-formed byte sequence in it. The
schemas are listed under
[Versioned JSON outputs](/docs/reference/cli/compatibility#versioned-json-outputs).
`apigenie-server` serving a document has `--log-format json` instead.

## Experimental commands

These commands are outside the [1.0 compatibility promise](/docs/reference/cli/compatibility):
their options and output can still change. Their `--help` and the first line they print (on the standard error, so that their output
stays usable) say "(experimental, outside the 1.0 compatibility promise)". `apigenie-mcp`, whose
standard output carries the protocol, says it only in its `--help`.

| Command | Why |
| ------- | --- |
| [`apigenie-catalog`](/docs/reference/catalog) | The first part of a catalog kept in Git; pinned consumers and multi-repository catalogs will add settings |
| [`apigenie-mcp`](/docs/reference/cli/mcp) | MCP is still moving; tool names, arguments and results can change with it |
| [`apigenie-generator client rust`](/docs/reference/generator/client-rust) | The generated crate isn't yet checked against a live API (conformance Level 3) |
| [`apigenie convert`](/docs/reference/cli/convert) | Three sources (`--to openapi32` for Swagger 2.0, `--to openapi31` for WSDL 1.1, `--to draft7|draft4|openapi30` for JSON Schema); more sources and targets may change its options |
| [`apigenie evolve plan`](/docs/reference/cli/evolve) | The first version of the planner: its recipes and `plan.yaml` will grow, and `evolve status` and `evolve next` will join it |
| [`apigenie-generator client swift`](/docs/reference/generator/client-swift) | The generated packages aren't yet built and run against a live API by the conformance suite |
| [`apigenie-generator schema zod`](/docs/reference/generator/schema-zod) | The generated schemas aren't yet checked against a live API (conformance Level 3) |
| [`apigenie-generator server axum`](/docs/reference/generator/server-axum) | The generated crate doesn't yet receive requests in contract tests (conformance Level 3) |
| [`apigenie-generator server hummingbird`](/docs/reference/generator/server-hummingbird) | Levels 2 and 3 of the conformance suite are wired but haven't passed a run yet |
| [`apigenie-generator server mcp`](/docs/reference/generator/server-mcp) | MCP and its SDK are still moving; tool names and result shapes can change with them |
| [`apigenie-generator server vapor`](/docs/reference/generator/server-vapor) | Levels 2 and 3 of the conformance suite are wired but haven't passed a run yet |

## Continuous integration

The [GitHub Action](/docs/ci/github-action) installs the CLI on GitHub Actions runners and lints,
checks the formatting of, or diffs your files on every pull request. On other CI systems, run the
commands and read their [exit statuses](#exit-status).

## Configuration files

Most commands read their settings from a configuration file: the rules of `lint`, the style of
`format`, the severities of `diff`, the options of each generator and the catalog.

`apigenie`, `apigenie-generator`, `apigenie-server` and `apigenie-catalog` find the file themselves: `apigenie.yaml`
(or `.yml`, `.json`, or the same names with a leading dot) in the current directory or a parent
directory, up to the root of the Git repository. `--config FILE` uses another file instead, and
`--no-config` none. The file is checked against its JSON Schema before any command reads it, so a
misspelled setting is an error that names its line and JSON pointer.
[`apigenie config`](/docs/reference/cli/config) prints the settings in effect and checks a
file. [Configuration](/docs/reference/cli/configuration) lists every setting.

### Editor support

The JSON Schema of the file is published at
`https://apigenie.pl/schemas/apigenie-config/latest.json`, and the schema of each release at
`https://apigenie.pl/schemas/apigenie-config/<version>.json`. Editors that use the YAML language
server (VS Code with the Red Hat YAML extension, Neovim, JetBrains IDEs, Zed) complete and check
the file when it starts with:

```yaml
# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json
version: '1.0'
commands:
  lint:
    extends: [recommended]
```

A standalone mock server file (`apigenie-server.yaml`) has its own schema,
`https://apigenie.pl/schemas/apigenie-server-config/latest.json`. The API Genie extension for VS Code
associates both schemas with `apigenie.yaml`, `apigenie-server.yaml` and their variants on its own.
To pin the schema to the version you run, use `apigenie config schema --out apigenie.schema.json`
and point the comment at that file.

## Telemetry

Nothing is sent anywhere, and no telemetry file is written unless you ask for one. With
`APIGENIE_TELEMETRY_FILE` set to a file path, each run writes a local log to that file: the
version, the commands run, the time taken by internal steps (parsing a YAML file, for example)
and the errors met, without usernames, API keys or the content of your files. A relative path is
resolved against the current directory; the file is created or truncated on each run, and its
parent directory must exist. When the variable is unset or empty, no file is created or
truncated.
