CLI reference
The apiome command-line client talks to the Apiome REST API. This reference is generated from the CLI's own command tree, so it lists exactly what the installed version accepts; apiome --help and apiome help <command> print the same help in a terminal. For a walkthrough, start with the CLI quick-start.
Usage
apiome [OPTIONS] COMMAND [ARGS]...
Global options
Global options go before the command, e.g. apiome --base-url http://localhost:8000 --json projects list.
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--version, -V | flag | Show the CLI version and exit. | ||
--base-url | text | REST API base URL (overrides APIOME_BASE_URL, config file, and .env). | ||
--tenant | text | Tenant UUID (overrides APIOME_TENANT_ID, config file, and .env). | ||
--api-key | text | API key for Tier 2 endpoints (overrides APIOME_API_KEY, config file, and .env). Prefer --api-key-file: a secret in argv is visible to other processes. | ||
--api-key-file | text | Read the API key from a file, or from stdin with '-'. | ||
--session-token | text | UI session bearer token for auth and PAT commands (overrides APIOME_SESSION_TOKEN, config file, and .env). Prefer --session-token-file. | ||
--session-token-file | text | Read the session token from a file, or from stdin with '-'. | ||
--env-file | text | Load settings from this dotenv file instead of the default package and cwd .env files. | ||
--json | flag | Emit raw API JSON on stdout (machine-readable). | ||
--verbose, --debug, -d, -v | flag | Show Python tracebacks on unexpected failures. | ||
--quiet, -q | flag | Suppress non-essential output. Errors and --json output are unaffected. | ||
--no-color | flag | Disable colour. Also honoured: NO_COLOR, APIOME_NO_COLOR, TERM=dumb, and any non-terminal stdout. | ||
--no-input | flag | Never prompt. Commands needing confirmation fail with the flag to pass instead of hanging. | ||
--timeout | float range | HTTP timeout in seconds (default 30; import wait uses 120 unless set). For imports, prefer the per-command --import-timeout. | ||
--no-progress | flag | Disable stderr progress spinner during long imports. | ||
--insecure | flag | Disable TLS certificate verification. For local development with self-signed certificates only. | ||
--install-completion | flag | Install completion for the current shell. | ||
--show-completion | flag | Show completion for the current shell, to copy it or customize the installation. |
Commands
| Command | What it does |
|---|---|
apiome auth | Inspect signed-in identity and accessible tenants. |
apiome checks | Run and read the API change check suite (one verdict for a pull request). |
apiome compat | Compare two OpenAPI revisions via independent oasdiff compatibility evidence. |
apiome config | Show or change saved defaults in the user config file. |
apiome contract | Compile and inspect executable contract suites for a version. |
apiome convert | Convert a catalog item to OpenAPI (POST .../convert); print the fidelity summary + warning. |
apiome diff | Diff a local OpenAPI file against a published project version (CI gate). |
apiome doctor | Quick connectivity check against the REST service (GET /health, no API key). |
apiome export | Export a version to a target format via the emitter registry. |
apiome formats | List the formats this deployment supports, in which directions and at which versions. |
apiome health | Check REST service health (GET /health). |
apiome help | Show concise usage, or --help for a subcommand. |
apiome import | Import OpenAPI, Swagger, Arazzo, JSON Schema, and JSON Schema type documents into Apiome. |
apiome lint | Score schema quality, list lint findings, and run the CI lint gate. |
apiome mcp | MCP catalog endpoints and tenant governance (policy / key capabilities). |
apiome mock | Manage the hosted mock for published project versions. |
apiome operations | Inspect OpenAPI operations for a project version. |
apiome paths | List and inspect OpenAPI path templates for a project version. |
apiome projects | List and fetch tenant projects. |
apiome properties | List and fetch tenant properties. |
apiome repos | List tenant Git repositories and inspect repository files. |
apiome repository | Repository auto-refresh: trigger a refresh and inspect per-file state. |
apiome schema | Test payloads against cataloged schemas (CI evidence). |
apiome schemas | List and fetch tenant schemas. |
apiome spec | Export reconstructed OpenAPI/Arazzo specs. |
apiome types | Browse tenant JSON Schema primitive types. |
apiome verify | Run executable contract verification and emit CI artifacts. |
apiome versions | List and fetch project versions. |
Exit codes
Every command exits 0 on success, 1 on an error and 2 on bad usage or a rejected request; the quality-gate and check commands add their own codes. See Exit codes.