Overview

API Genie CLI streamlines Web API development by providing a command-line interface for managing, testing and generating artifacts from OpenAPI, Swagger, AsyncAPI, Protobuf and GraphQL descriptions.

From 1.0.0 the commands, options, configuration keys, exit statuses and JSON outputs follow semantic versioning; Compatibility says what that covers.

Key functionality

Subcommand	Description
bundle	Combines a schema or a Protobuf file and the files it uses into one file
changelog	Builds the changelog of a spec from its Git history
convert	Converts Swagger 2.0 specs to OpenAPI 3.2, WSDL 1.1 to OpenAPI 3.1, and JSON Schema 2019-09/2020-12 to draft-07, draft-04 or the OpenAPI 3.0 dialect
diff	Compares OpenAPI, Swagger or AsyncAPI schemas, or Protobuf or GraphQL files, and detects breaking changes
evolve	Plans safe API changes: an expand wave and a contract wave for a breaking OpenAPI change (experimental)
format	Formats schemas to your team’s standards
i18n	Extracts texts for translation and applies translations
lint	Validates schemas for best practices
overlay	Applies OpenAPI Overlays to schemas
test	Runs requests against a live API and checks them against its contract
credits, license	Show the licenses of API Genie and its dependencies

Commands marked experimental are outside the 1.0 compatibility promise; see Experimental commands.

The four binaries

API Genie installs four 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)

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 and apigenie-catalog 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 four 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
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.

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)”.

Command	Why
apigenie-catalog	The first part of a catalog kept in git; release tags, pinned consumers and multi-repository catalogs will add settings
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 schema zod	The generated schemas aren’t yet checked against a live API (conformance Level 3)
apigenie-generator server mcp	MCP and its SDK are still moving; tool names and result shapes can change with them

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.

Supported file formats

Input to most CLI commands are one or more OpenAPI schemas. All commands recognize schemas in JSON or YAML formats.

Configuration files

Apart from OpenAPI schemas, most CLI commands also accept input from configuration file. The file contains configuration for commands, based on best practices and guidelines in your organization.

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.

See the configuration section for detailed description of this file.

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

API Genie CLI can record anonymous usage data locally to help debug the tool and identify areas for improvement. Local telemetry logging is disabled by default.

The telemetry data is limited to technical details about how you use the CLI, such as:

• Version of the CLI
• Commands used
• Performance metrics for internal tasks (e.g., time taken to parse YAML files)
• Errors encountered by users (anonymized)

No personal information is collected. This includes usernames, API keys, or any data specific to your API interactions.

The local log can help with:

• Identifying common usage patterns and workflows
• Debugging and resolving technical issues
• Prioritizing feature development based on user needs

To opt in to a local telemetry log, set APIGENIE_TELEMETRY_FILE to the desired file path before running apigenie. Relative paths are resolved against the current directory. The file is created or truncated on each invocation; its parent directory must already exist.

When the variable is unset or empty, no file telemetry is initialized and the CLI does not create or truncate .apigenie.telemetry. Telemetry is stored locally, not sent to a remote service.