Command reference

This document contains the help content for the apifae command-line program.

Command Overview:

• apifae↴
• apifae init↴
• apifae serve↴
• apifae up↴
• apifae push↴
• apifae pull↴
• apifae validate↴
• apifae login↴
• apifae logout↴
• apifae status↴
• apifae scenario↴
• apifae scenario list↴
• apifae scenario set↴
• apifae scenario reset↴
• apifae scenario create↴
• apifae config↴
• apifae config list↴
• apifae config set↴
• apifae config get↴
• apifae config add↴
• apifae config remove↴
• apifae ca↴
• apifae ca list↴
• apifae ca remove↴
• apifae diff↴
• apifae patch↴
• apifae record↴

apifae

APIFae CLI - API mocking for developers

Usage: apifae [OPTIONS] <COMMAND>

Subcommands:

• init — Initialize a new APIFae project, importing any OpenAPI spec found here
• serve — Start local mock server
• up — Start local mock server (quick start)
• push — Would push local schemas to APIFae cloud, which does not exist yet
• pull — Would pull schemas from APIFae cloud, which does not exist yet
• validate — Validate mocks against the workspace OpenAPI spec
• login — Would authenticate this machine against APIFae cloud, which does not exist yet
• logout — Would end this machine's APIFae cloud session, which does not exist yet
• status — Show project and sync status
• scenario — Manage scenarios
• config — Manage configuration
• ca — Inspect and remove the recording CA certificates APIFae has written
• diff — Compare mocks against a live API, and the live API against the spec
• patch — Auto-update mocks from live API responses
• record — Record traffic from a live API

Options:

• -v, --verbose — Verbose output
• -c, --config <CONFIG> — Configuration file path (overrides workspace detection)

apifae init

Initialize a new APIFae project, importing any OpenAPI spec found here

Detects an OpenAPI 3.x / Swagger spec in the directory (openapi.yaml, swagger.json, api/*.yaml, …), copies it to schemas/ and generates one mock per documented path, populated from the spec's example: values — so apifae init && apifae up serves the documented API straight away. Each declared error response is kept too, reachable through a scenario in scenarios/from-spec.yaml.

With no spec present, a commented example mock is written instead.

Usage: apifae init [OPTIONS] [PATH]

Arguments:

• <PATH> — Project directory

  Default value: .

Options:

• -n, --name <NAME> — Project name

• -p, --port <PORT> — Server port

• -f, --force — Force overwrite existing workspace

• -N, --non-interactive [alias: ni] — Disable interactive prompts

  A detected OpenAPI spec is still imported: the non-interactive default matches what the prompt defaults to. Pass --no-import to opt out.

• --import <IMPORT> — What to do with a detected OpenAPI spec

  full: copy it to schemas/ and generate mocks (the default). reference: record its path only. skip: ignore it.

  Possible values:

  • full: Copy the spec to schemas/ and generate mocks from it
  • reference: Record the spec's path without copying it
  • skip: Ignore the detected spec

• --no-import — Do not import a detected OpenAPI spec (same as --import skip)

apifae serve

Start local mock server

Usage: apifae serve [OPTIONS]

Options:

• -p, --port <PORT> — Port to listen on

  Overrides server.port in apifae.yaml. Left unset, the workspace's own port applies.

• --watch — Enable hot-reload on file changes

  Default value: true

• --no-watch — Disable file watching

• --no-reload — Disable config-file hot reload

• --seed <N> — Make uuid(), now() and the fake_* helpers reproducible

  Every response to the same method, path and query is then byte-identical across runs, processes and machines, so a Playwright or Cypress suite can assert on the body. Overrides server.seed in apifae.yaml. Without it, the helpers stay random.

apifae up

Start local mock server (quick start)

Usage: apifae up [OPTIONS]

Options:

• -p, --port <PORT> — Port to listen on

• -d, --debug — Enable debug mode (verbose logging, detailed 404s)

• -w, --watch — Watch for file changes

  Default value: true

• --no-watch — Disable file watching

• --no-reload — Disable config-file hot reload (mock-file watching unaffected)

• --strict — Refuse to start if any mock disagrees with the OpenAPI spec

• --scenario <SCENARIO> — Pre-activate a scenario on startup

• --seed <N> — Make uuid(), now() and the fake_* helpers reproducible

  Every response to the same method, path and query is then byte-identical across runs, processes and machines, so a Playwright or Cypress suite can assert on the body. Overrides server.seed in apifae.yaml. Without it, the helpers stay random.

apifae push

Would push local schemas to APIFae cloud, which does not exist yet

Usage: apifae push

apifae pull

Would pull schemas from APIFae cloud, which does not exist yet

Usage: apifae pull

apifae validate

Validate mocks against the workspace OpenAPI spec

Exits 1 on errors — a mock that disagrees with the spec, or a file that will not load. Mocks the spec does not describe are warnings, and exit 0 unless --strict is given.

Usage: apifae validate [OPTIONS]

Options:

• --strict — Also fail on warnings (mocks with no matching operation in the spec)
• -v, --verbose — Verbose output with full error details

apifae login

Would authenticate this machine against APIFae cloud, which does not exist yet

Usage: apifae login

apifae logout

Would end this machine's APIFae cloud session, which does not exist yet

Usage: apifae logout

apifae status

Show project and sync status

Usage: apifae status [OPTIONS]

Options:

• -p, --port <PORT> — Port to probe for a running mock server (default: the workspace's)
• --json — Output the status as JSON

apifae scenario

Manage scenarios

Usage: apifae scenario <COMMAND>

Subcommands:

• list — List all defined scenarios
• set — Set the active scenario (requires running server)
• reset — Reset to default (no active scenario)
• create — Create a new scenario file

apifae scenario list

List all defined scenarios

Usage: apifae scenario list

apifae scenario set

Set the active scenario (requires running server)

Usage: apifae scenario set [OPTIONS] <NAME>

Arguments:

• <NAME> — Scenario name to activate

Options:

• -p, --port <PORT> — Server port (default: 4000)

apifae scenario reset

Reset to default (no active scenario)

Usage: apifae scenario reset [OPTIONS]

Options:

• -p, --port <PORT> — Server port (default: 4000)

apifae scenario create

Create a new scenario file

Usage: apifae scenario create [OPTIONS] <NAME>

Arguments:

• <NAME> — Scenario name

Options:

• -i, --interactive — Interactive wizard mode

apifae config

Manage configuration

Usage: apifae config <COMMAND>

Subcommands:

• list — Show effective configuration with source annotations
• set — Set a configuration value
• get — Show a single config key's effective value and source
• add — Append a value to a list config key (e.g. schemas)
• remove — Remove a list item, or delete a map entry (e.g. auth.headers.X-Api-Key)

apifae config list

Show effective configuration with source annotations

Usage: apifae config list [OPTIONS]

Options:

• --format <FORMAT> — Output format (text or json)
• --filter <FILTER> — Filter keys by prefix (e.g., "server")

apifae config set

Set a configuration value

Usage: apifae config set [OPTIONS] <KEY> <VALUE>

Arguments:

• <KEY> — Config key in dotted notation (e.g., server.port)
• <VALUE> — Value to set

Options:

• --global — Write to global config (~/.apifae/config.yaml) instead of workspace

apifae config get

Show a single config key's effective value and source

Usage: apifae config get [OPTIONS] <KEY>

Arguments:

• <KEY> — Config key in dotted notation (e.g., server.port)

Options:

• --format <FORMAT> — Output format (text or json)

apifae config add

Append a value to a list config key (e.g. schemas)

Usage: apifae config add [OPTIONS] <KEY> <VALUE>

Arguments:

• <KEY> — List config key (e.g. schemas, convert.denied_headers)
• <VALUE> — Value to append

Options:

• --global — Write to global config (~/.apifae/config.yaml) instead of workspace

apifae config remove

Remove a list item, or delete a map entry (e.g. auth.headers.X-Api-Key)

Usage: apifae config remove [OPTIONS] <KEY> [VALUE]

Arguments:

• <KEY> — Config key: a list key, or a map entry like auth.headers.X-Api-Key
• <VALUE> — Value to remove (required for list keys; omit for map entries)

Options:

• --global — Write to global config (~/.apifae/config.yaml) instead of workspace

apifae ca

Inspect and remove the recording CA certificates APIFae has written

record --init-ca asks you to trust a root certificate. This is how you see what that left behind and take it back out. It reads what APIFae wrote on disk; it cannot see your system trust store, and says so.

Usage: apifae ca <COMMAND>

Subcommands:

• list — List the recording CAs APIFae has written on this machine
• remove — Delete a recording CA, and print how to untrust it

apifae ca list

List the recording CAs APIFae has written on this machine

Usage: apifae ca list

apifae ca remove

Delete a recording CA, and print how to untrust it

Removes the certificate and key APIFae wrote. It cannot remove the certificate from your system trust store — that needs your own sudo — so it prints the command to do that.

Usage: apifae ca remove [OPTIONS]

Options:

• --workspace — Remove this workspace's own CA instead of the machine-wide one
• --all — Remove every APIFae CA visible from here
• -y, --yes — Do not ask for confirmation

apifae diff

Compare mocks against a live API, and the live API against the spec

Exit codes: 0 clean, 1 drift and/or a contract violation, 2 the run could not complete (connection refused, timeout, 401, 403). Endpoints that could not be checked are reported but do not fail the run unless --fail-on-skip is given.

Requests are issued for every method the mocks declare, including POST, PUT, PATCH and DELETE, against the URL you give it.

Every response variant is probed: a response with a when: block is compared against a request built to satisfy that block. A variant selecting on the request body, on a regex, or on a scenario is reported as skipped rather than guessed at.

Usage: apifae diff [OPTIONS] <URL>

Arguments:

• <URL> — Base URL of the live API (e.g., https://api.example.com)

Options:

• -t, --timeout <TIMEOUT> — Request timeout in milliseconds. Overrides timeouts.request.

  Left off, the workspace's timeouts.request applies, then 5000.

• -d, --debug — Show detailed debug output

• --json — Output results as JSON

• --values — Also report same-type value changes against the mock (e.g. "1.0" → "2.0")

  Values the SPEC forbids — anything outside a declared enum — are always reported and do not need this flag.

• --fail-on-skip — Fail when an endpoint or variant could not be checked (default: report only)

• --samples <N> — Requests to issue per endpoint, reporting how often each response shape was seen. Catches intermittent drift a single request misses

  Default value: 1

• --path-param <NAME=VALUE> — Value for a path placeholder, e.g. --path-param id=ord_123

  Repeatable. Beats every value inferred from the mock or the spec.

apifae patch

Auto-update mocks from live API responses

Usage: apifae patch [OPTIONS] <URL>

Arguments:

• <URL> — Base URL of the live API (e.g., https://api.example.com)

Options:

• -t, --timeout <TIMEOUT> — Request timeout in milliseconds. Overrides timeouts.request.

  Left off, the workspace's timeouts.request applies, then 5000.

• --dry-run — Preview changes without modifying files

• -i, --interactive — Prompt before applying each change

• -d, --debug — Show detailed debug output

• --values — Also patch same-type value changes (e.g. "1.0" → "2.0")

• --accept-violations — Write values the workspace's OpenAPI spec forbids

  By default patch refuses to entrench a live response that breaks the published contract, since doing so makes diff report clean on a broken API.

apifae record

Record traffic from a live API

Usage: apifae record [OPTIONS] [URL]

Arguments:

• <URL> — Target API URL (e.g., https://api.example.com)

Options:

• -p, --port <PORT> — Local proxy port

  Default value: 4001

• -n, --name <NAME> — Session name to record under, or with --convert the session to convert (default: timestamp-based)

• --single-file — Merge all recordings into a single traffic.yaml file

• --init-ca — Generate CA certificate for HTTPS interception

• --list — List previous recording sessions

• --convert — Convert recordings to mock YAML files

• --responses <RESPONSES> — Response aggregation strategy: singular (default), full, compacted

  Default value: singular

  Possible values: singular, full, compacted

• --non-interactive — Skip confirmation prompts

Exit codes

Every command returns 2 for a usage error — an unknown flag, a missing argument. It is not repeated per command below.

apifae init

apifae serve

apifae up

apifae validate

apifae status

apifae diff

apifae patch

apifae record

apifae ca

apifae ca list

apifae ca remove

apifae scenario

apifae scenario list

apifae scenario set

apifae scenario reset

apifae scenario create

apifae config

apifae config list

apifae config get

apifae config set

apifae config add

apifae config remove

apifae login

apifae logout

apifae push

apifae pull