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.