# Overview

Source: https://apigenie.pl/docs/reference/cli/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](/docs/reference/cli/compatibility) says what that covers.

## Key functionality

| Subcommand | Description |
| ---------- | ----------- |
| [bundle](/docs/reference/cli/bundle) | Combines a schema or a Protobuf file and the files it uses into one file |
| [changelog](/docs/reference/cli/changelog) | Builds the changelog of a spec from its Git history |
| [convert](/docs/reference/cli/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](/docs/reference/cli/diff) | Compares OpenAPI, Swagger or AsyncAPI schemas, or Protobuf or GraphQL files, and detects breaking changes |
| [evolve](/docs/reference/cli/evolve) | Plans safe API changes: an expand wave and a contract wave for a breaking OpenAPI change (experimental) |
| [format](/docs/reference/cli/format) | Formats schemas to your team's standards |
| [i18n](/docs/reference/cli/i18n) | Extracts texts for translation and applies translations |
| [lint](/docs/reference/cli/lint) | Validates schemas for best practices |
| [overlay](/docs/reference/cli/overlay) | Applies OpenAPI Overlays to schemas |
| [test](/docs/reference/cli/test) | Runs requests against a live API and checks them against its contract |
| [credits](/docs/reference/cli/credits), [license](/docs/reference/cli/license) | Show the licenses of API Genie and its dependencies |

Commands marked *experimental* are outside the
[1.0 compatibility promise](/docs/reference/cli/compatibility); see
[Experimental commands](#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`](/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) |

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:

```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 four 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 |
| 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](/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)".

| Command | Why |
| ------- | --- |
| [`apigenie-catalog`](/docs/reference/catalog) | The first part of a catalog kept in git; release tags, pinned consumers and multi-repository catalogs will add settings |
| [`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 schema zod`](/docs/reference/generator/schema-zod) | The generated schemas aren't yet checked against a live API (conformance Level 3) |
| [`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 |

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

## 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`](/docs/reference/cli/config) prints the settings in effect and checks a
file.

See the [configuration](/docs/reference/cli/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
# 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.