apigenie

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, apigenie-server, apigenie-catalog and apigenie-mcp.

From 1.0.0 the commands, options, configuration keys, exit statuses and JSON outputs follow semantic versioning; 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

apigenie COMMAND [OPTIONS] [FILES]

Commands

Command What it does
apigenie bundle Combines an OpenAPI, Swagger 2.0 or AsyncAPI document, or a Protobuf file, and the files it references into one file
apigenie changelog Builds the changelog of an OpenAPI, Swagger 2.0, AsyncAPI, Protobuf or GraphQL file from its Git history
apigenie config Prints the configuration in effect, checks a configuration file and prints its JSON Schema
apigenie 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 Lists the third-party libraries API Genie uses, with their licenses
apigenie 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 Splits a breaking OpenAPI change into an expand wave and a contract wave (experimental)
apigenie format Puts OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files in one style
apigenie i18n Extracts the texts of OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files for translation, and applies translations
apigenie 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 Prints the license of API Genie and of the libraries it uses
apigenie lint Checks OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files against the rules of their standard
apigenie overlay Applies OpenAPI Overlays to an OpenAPI document
apigenie 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; see 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 Generates clients, servers, documentation, data and validation schemas from OpenAPI, Swagger, AsyncAPI and JSON Schema documents
apigenie-server Serves a document as a mock server, or proxies a live API and checks the traffic against the contract
apigenie-catalog Lists the API specifications of a repository and keeps their names and owners in apigenie.yaml (experimental)
apigenie-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:

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

apigenie config check --json missing.yaml
{
  "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. apigenie-server serving a document has --log-format json instead.

Experimental commands

These commands are outside the 1.0 compatibility promise: 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 The first part of a catalog kept in Git; pinned consumers and multi-repository catalogs will add settings
apigenie-mcp MCP is still moving; tool names, arguments and results can change with it
apigenie-generator client rust The generated crate isn’t yet checked against a live API (conformance Level 3)
apigenie convert Three sources (--to openapi32 for Swagger 2.0, --to openapi31 for WSDL 1.1, `–to draft7
apigenie evolve plan 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 The generated packages aren’t yet built and run against a live API by the conformance suite
apigenie-generator schema zod The generated schemas aren’t yet checked against a live API (conformance Level 3)
apigenie-generator server axum The generated crate doesn’t yet receive requests in contract tests (conformance Level 3)
apigenie-generator server hummingbird Levels 2 and 3 of the conformance suite are wired but haven’t passed a run yet
apigenie-generator server mcp MCP and its SDK are still moving; tool names and result shapes can change with them
apigenie-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 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.

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 prints the settings in effect and checks a file. 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-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.

Was this helpful?