---
title: "CLI"
description: "Every apiweld command, what it changes, and the flags they all share."
---

> Documentation Index
> Fetch the complete documentation index at: https://apiweld.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

The CLI is how you and your CI use Apiweld. Your agent uses the same commands through the [MCP server](/mcp), so anything it does in chat you can run again in a terminal or a workflow.

Every command accepts two flags:

- `--json` prints machine-readable output for scripts, CI, and agents.
- `--offline` uses only the local cache and the lockfile, and never fetches.

Run `apiweld` or `apiweld --help` for the command list, and `apiweld <command> --help` for one command.

## Set up

| Command | What it does |
| --- | --- |
| `apiweld init [--agents] [--output dir]` | Creates `apiweld.config.ts` and adds `.apiweld/` to `.gitignore`. In a monorepo it asks where generated clients go, unless you pass `--output`. `--agents` adds a note and an MCP snippet to `AGENTS.md` and `CLAUDE.md`. |
| `apiweld mcp` | Starts the MCP server on stdio for your agent. |

## Find APIs

| Command | What it does |
| --- | --- |
| `apiweld catalog add <id> <url>` | Fetches one API's spec and adds its endpoints to the local catalog. The rest of the catalog is unchanged. |
| `apiweld catalog sync [--url url]` | Downloads the prebuilt catalog snapshot of the APIs.guru directory and checks its SHA-256 before using it. |
| `apiweld catalog build` | Indexes the whole APIs.guru directory, plus any extra sources in your settings, on your machine. This takes a while. Use `catalog add` if you only need a few APIs. |
| `apiweld search <query> [--ops] [--api id]` | Searches APIs by name and description. With `--ops`, searches endpoints instead, optionally within one API. |
| `apiweld show <api> [operation] [--depth n]` | Describes an API, or one endpoint as a short TypeScript-style signature. `--depth` expands nested types. |

## Manage clients

| Command | What it does |
| --- | --- |
| `apiweld add <api> <operation>… [--source src] [--as name]` | Adds endpoints to the config, generates the client, and updates the lock. `--source` sets the spec when the API isn't in the catalog yet. `--as` picks a different config key and folder name. |
| `apiweld remove <api> <operation>…` | Removes endpoints and regenerates a smaller client. |
| `apiweld generate [api]` | Rebuilds clients from the lockfile and the cached spec. Doesn't use the network. |

An operation is either an operation id (`PostRefunds`) or a quoted `METHOD /path` (`"POST /v1/refunds"`). The config and the lockfile always store `METHOD /path`.

## Stay in sync

| Command | What it does |
| --- | --- |
| `apiweld check [api] [--fail-on breaking\|risky]` | Fetches the latest spec and reports changes to your selected endpoints. Exits non-zero when it finds a change at or above `--fail-on`. |
| `apiweld update [api]` | Runs `check`, then regenerates when the API's policy allows it. Breaking changes are never applied automatically. |
| `apiweld heal <api> [--apply]` | Writes a heal plan for a breaking change. `--apply` puts the regenerated client into your working tree so you or your agent can fix the call sites. |
| `apiweld verify` | Type-checks the project, then runs your test command if you configured one. |

See [Drift detection](/drift) for how changes are classified and [Heal loop](/heal) for the fix workflow.

## Use check in CI

`apiweld check` fails the job when it finds a breaking change. Use `--fail-on risky` to also fail on changes that might break you, such as a field becoming nullable or an endpoint being deprecated.

```sh
npx apiweld check
npx apiweld check stripe --fail-on risky --json
```

Each run also writes JSON and Markdown reports to `.apiweld/reports/`. That folder is gitignored.

To open a pull request automatically when drift is found, use the [GitHub Action](/heal#in-ci).

## When add can't edit your config

`add` and `remove` edit `apiweld.config.ts` in place and keep your formatting, comments, and functions. If the config is built dynamically, for example with computed keys or values spread in from another file, Apiweld can't edit it safely. It prints the snippet to paste in and leaves the file alone.

## Environment variables

| Variable | Effect |
| --- | --- |
| `APIWELD_OFFLINE=1` | Same as passing `--offline` to every command. |
| `APIWELD_CACHE_DIR` | Uses a different cache folder instead of `~/.apiweld/`. |
| `APIWELD_ENGINE_PATH` | Uses an `apiweld-engine` binary you built yourself instead of the one npm installed. |
| `APIWELD_DRIFT_LOG` | Writes the runtime drift log somewhere other than `.apiweld/drift.log.jsonl`. |

Settings that apply to every project on your machine, such as a proxy, offline by default, or extra catalogs, go in `~/.apiweld/settings.json`. See [Config and lockfile](/config#machine-settings).

Source: https://apiweld.dev/cli/index.mdx