The CLI is how you and your CI use Apiweld. Your agent uses the same commands through the MCP server, so anything it does in chat you can run again in a terminal or a workflow.
Every command accepts two flags:
--jsonprints machine-readable output for scripts, CI, and agents.--offlineuses 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 for how changes are classified and Heal loop 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.
npx apiweld check
npx apiweld check stripe --fail-on risky --jsonEach 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.
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.