---
title: "Principles"
description: "The eight rules that shape Apiweld, and what each one rules out."
---

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

# Principles

These rules decide what Apiweld does and, just as often, what it won't do. When a design question comes up, the answer starts here. If a feature would need an account, a call to a language model, or a server you don't run, it doesn't belong in Apiweld.

## Nothing leaves your machine

The only network requests are HTTP GETs for public specs and for the optional catalog snapshot. Both are cached. With a warm cache, or with `APIWELD_OFFLINE=1`, search, generation, and diffs run with no network at all. There's no telemetry and no account.

## Your agent does the thinking

Apiweld never calls a language model. Everything it does (search, slicing, generation, diffs, type-checks) is deterministic: same input, same output. Your coding agent, whether that's Claude Code, Cursor, or any other MCP client, does the reasoning and edits your code through the [MCP tools](/mcp). Every tool matches a [CLI](/cli) command, so you or your CI can reproduce anything the agent did.

## Git is the database

A project's state is two committed files: `apiweld.config.ts` and `apiweld.lock.json`. There's no database to migrate and no dashboard to log in to. Reviewers see every change to a client in the diff, and a fresh checkout plus the lock rebuilds the same client. See [Config and lockfile](/config).

## Only what you use

Generated code, drift checks, and alerts cover only the endpoints you selected. A change to an endpoint you don't call never produces an alert. Apiweld follows each selected endpoint's parameters, request and response bodies, and the schemas they reference, then hashes the result. Only a change to that set is worth interrupting you for.

## Never auto-merge a breaking change

Safe changes can regenerate automatically if you allow it for that API. Breaking changes produce a [heal plan](/heal) and a branch, and a person reviews them. Apiweld never merges anything, and in CI it only acts with the token you give it.

## Reuse what already works

Apiweld doesn't reinvent code generation or spec diffing. TypeScript clients come from Hey API (`@hey-api/openapi-ts`), and Go clients come from oapi-codegen. Diffs and breaking-change rules come from the oasdiff Go library, wrapped in a small binary called `apiweld-engine`. Apiweld supplies the catalog, the slicing, the lockfile, and the workflow around them.

## Adapters at the edges

Spec sources and code generators sit behind small interfaces. Adding a new generator (another language) or a new kind of source (a private catalog) doesn't require changes to search, slicing, or the lock. Today that means two generators (Hey API and oapi-codegen) and four kinds of source: a URL, a local file, APIs.guru, and a provider's `.well-known` catalog.

## TypeScript for config, JSON for machine state

You edit `apiweld.config.ts`. Your editor type-checks and autocompletes it, and it can hold functions, such as a spec patch, that a data format can't express. Apiweld writes `apiweld.lock.json` with sorted keys, so its diffs stay small. There's no YAML.

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