---
title: "Quickstart"
description: "Go from an empty repo to a committed, typed Stripe refund client, from the terminal or through your coding agent."
---

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

# Quickstart

This guide adds a typed client for two Stripe endpoints: create a refund and retrieve a refund. The steps are the same for any API with an OpenAPI spec.

You need Node.js 20 or newer. Install Apiweld as a dev dependency. The CLI and the MCP server are the same package.

```sh
npm install --save-dev apiweld
pnpm add -D apiweld
yarn add -D apiweld
bun add -d apiweld
```

> **Nothing to sign up for**
>
> Apiweld has no account or cloud project. Every command writes files in the repo you run it in, or in its cache at `~/.apiweld/`.

## Add your first client

1. **Create the config**

```sh
npx apiweld init --agents
```

   This writes `apiweld.config.ts` and adds `.apiweld/` (local reports and logs) to `.gitignore`. `--agents` also adds a short section to both `AGENTS.md` and `CLAUDE.md`, creating them if needed. It tells your agent to use Apiweld instead of writing HTTP calls by hand and includes an MCP config snippet.

   Generated clients go in `src/apis/` by default. In a monorepo, `init` lists your workspace packages and asks where they should go. Press Enter to keep the default, or pass `--output`:

```sh
npx apiweld init --output packages/web/src/apis
```

   The config is written to the directory you run `init` in. To keep it next to one app in a monorepo, run `init` from that app's folder.
2. **Add the API to your catalog**

   Search runs against a local catalog. Add the providers your project uses by pointing Apiweld at their OpenAPI spec:

```sh
npx apiweld catalog add stripe https://github.com/stripe/openapi/blob/master/latest/openapi.spec3.json
```

   GitHub `blob` links are fine. Apiweld fetches the raw file. To index the whole [APIs.guru](https://apis.guru) directory up front, run `catalog sync` to download a prebuilt snapshot, or `catalog build` to index it yourself (slow).
3. **Find the endpoints**

   Search by what you want to do. `--ops` searches endpoints instead of APIs.

```sh
npx apiweld search "refund a payment" --ops
```

   `show` prints an endpoint as a short TypeScript signature, which is easier to read than raw OpenAPI:

```sh
npx apiweld show stripe PostRefunds
```
4. **Generate the client**

   Pass the endpoints you want, either as operation ids or as `METHOD /path`. These two commands do the same thing:

```sh
npx apiweld add stripe PostRefunds GetRefundsRefund
npx apiweld add stripe "POST /v1/refunds" "GET /v1/refunds/{refund}"
```

   You now have three changes to commit:

   - `apiweld.config.ts` lists the two endpoints under `stripe`.
   - `src/apis/stripe/` contains the generated client.
   - `apiweld.lock.json` pins the exact spec it was built from.

   The key (`stripe`) is the folder name and the name you import from. Pass `--as` to choose a different one.
5. **Call it**

   The client exports one function per endpoint, named after the operation id, plus the request and response types.

```ts
import { client } from "./apis/stripe/client.gen";
import { postRefunds } from "./apis/stripe";

client.setConfig({
  headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});

const { data: refund, error } = await postRefunds({
  body: { payment_intent: "pi_123", reason: "requested_by_customer" },
});
```

   Your API keys stay in your environment. Apiweld never sees them.

## Let your agent do it

Register the MCP server with your agent once. For Claude Code:

```sh
claude mcp add apiweld -- npx apiweld mcp
```

For Cursor and other clients, see [MCP tools](/mcp). After that, you can ask for what you need ("refund a Stripe payment when an order is cancelled") and the agent searches, adds the endpoints, and writes the call. Each tool matches a command from this guide, so you can re-run anything the agent did yourself.

## Keep it up to date

Run `check` whenever you like, or on a schedule in CI. It only reports changes to the endpoints in your config.

```sh
npx apiweld check
```

To rebuild the client from the lock without touching the network, for example in CI to confirm the committed files match, run:

```sh
npx apiweld generate
npx apiweld verify
```

`verify` type-checks the project with its own `tsconfig.json`, then runs your test command if you configured one.

Next: [how drift is classified](/drift), or the full [CLI reference](/cli).

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