# FAQ

Source: https://apigenie.pl/docs/faq

The questions teams ask before they adopt API Genie, with the answer and where the reference
says it. For a command that misbehaves, see [Troubleshooting](/docs/troubleshooting).

## Does anything leave my machine?

No. The command-line tools open no connection unless a command names a server: nothing is sent
anywhere, and no telemetry file is written unless `APIGENIE_TELEMETRY_FILE` names one, in which
case each run writes a local log of the version, the commands, the time taken by internal steps
and the errors met, without usernames, API keys or the content of your files
([Telemetry](/docs/reference/cli#telemetry)).

- `apigenie lint`, `format`, `diff`, `bundle` and `convert` read files: remote `$ref` URLs are not
  supported ([bundle](/docs/reference/cli/bundle)).
- `apigenie-catalog` lists the specifications of the repository and writes names and owners into
  `apigenie.yaml`; the repository is the catalog, nothing is uploaded
  ([`apigenie-catalog`](/docs/reference/catalog)).
- `apigenie test` and `apigenie-server --proxy-to` send requests to the server you name, and to
  no one else ([test](/docs/reference/cli/test), [contract testing](/docs/reference/server/contract-testing)).
- The [editor](/tools/editor) opens a spec of your machine in the browser and writes back to
  it; its Try it out sends the requests you fire to the server of the document
  ([hosts](/docs/reference/editor/hosts#try-it-out)).
- The documentation site `apigenie-generator docs` writes is built on your machine; its
  `npm install` fetches its dependencies from the npm registry
  ([docs](/docs/reference/generator/docs)).

## Which versions of the standards do the tools read?

| Standard | Read | Not read |
| --- | --- | --- |
| OpenAPI | 3.0, 3.1 and 3.2 | |
| Swagger | 2.0 | `apigenie-generator data` takes Swagger 2.0 after [`apigenie convert --to openapi32`](/docs/reference/cli/convert) |
| AsyncAPI | 3 | AsyncAPI 2 documents are rejected |
| Protobuf | proto3 | proto2 and editions files are rejected |
| GraphQL | schemas and operations | |

The [linter rules](/docs/linter) say per standard what each linter reads; the generators' pages
say which documents each target takes ([`apigenie-generator`](/docs/reference/generator)).

## Does it replace Spectral?

For linting, yes: `apigenie lint` has built-in rulesets per standard, takes custom rules in
Spectral's format (`given`, `then`, the core functions and JavaScript functions), disables a rule
in one place with `x-apigenie-lint-disable`, fixes what has a safe fix with `--fix`, and writes
the same report formats for CI. [Migrate from Spectral](/docs/guides/migrate-from-spectral) maps
the rules of `spectral:oas` by name, moves the custom rules and functions over, and lists what
has no counterpart. Spectral has no formatter, differ, mock or generator, so nothing else moves.

## Does it run on Windows?

Yes. [Downloads](/downloads) has a zip for Windows x64 with the five executables, and
`npm install -g @mykulyak/api-genie` installs the same binaries wherever Node.js 18 or later
runs. The other builds are Linux x64 (an archive, a `.deb` and an `.rpm`) and macOS on Apple
silicon (also Homebrew, which serves Linux too). The [Quickstart](/docs/quickstart#install) has
the commands for each channel.

## Is there a Docker image?

Two, built for `linux/amd64`: `mykulyak/apigenie` with `apigenie` and `apigenie-generator`, and
`mykulyak/apigenie-server` with the mock. Both work in `/mnt/data`, where you mount the directory
of your files ([Quickstart](/docs/quickstart#docker)).

## Does it work behind a proxy, or with a private certificate authority?

The commands that read files make no connection, so a proxy doesn't matter to them. `apigenie test`
and `apigenie-server --proxy-to` connect to the server you name directly: the tools don't read
`HTTP_PROXY` or `HTTPS_PROXY`. A private authority is given with `--ca-cert` (repeatable), a
client certificate with `--client-cert` and `--client-key`, and `--insecure` skips the
verification of the server's certificate while the traffic stays encrypted
([test](/docs/reference/cli/test#options), [server](/docs/reference/server#options),
[TLS](/docs/reference/server/tls)). `apigenie-server` serves TLS itself with `--tls-cert` and
`--tls-key`.

## What does it cost, and under which license?

The command-line tools are free ([pricing](/pricing)). `apigenie license` prints the license
text, and `apigenie license --list` the open source libraries the tools are built with
([credits](/credits)).

## Can scripts and CI rely on the output?

From 1.0.0 the command names, the options, the configuration keys, the environment variables, the
exit statuses, the `formatVersion` of each JSON report, the admin API and the `x-apigenie-*`
extensions follow semantic versioning; the text of the messages, the wording of `--help`, the
inside of generated code and the experimental commands don't. Versions below 1.0.0 make no such
promise, and the changelog lists what each one broke. The
[compatibility promise](/docs/reference/cli/compatibility) says what is covered and how
deprecation works; read the JSON, SARIF, checkstyle, TAP or JUnit output in scripts, not the text
formatters.

## Where do I ask a question or report a bug?

In an issue at [github.com/mykulyak/api-genie/issues](https://github.com/mykulyak/api-genie/issues),
with the output of `apigenie --version`, the command line, and the document or a reduced one
that shows the behaviour. A break of something the compatibility promise covers is a bug, fixed
in a patch release.
