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

# anvil init: Scaffold a New Anvil JS Project

> Scaffold package.json, tsconfig.json, and starter routes for a new Anvil project — pick from a basic API, MCP server, or agent route template.

Run `anvil init` to scaffold a new Anvil project, or add Anvil to an existing one. It writes `package.json` (creating or merging into an existing file), `tsconfig.json`, `.gitignore`, and a starter route or two from a template you choose.

## Usage

```bash theme={null}
anvil init [dir] [options]
```

`dir` is the target directory. Defaults to the current directory. It's created if it doesn't exist.

## Flags

<ParamField query="-t, --template <name>" type="string">
  Template to scaffold: `basic`, `mcp`, or `agent`. Skips the interactive prompt.
</ParamField>

<ParamField query="-y, --yes" type="boolean">
  Skip the interactive prompt without specifying `--template` — defaults to the `basic` template. Useful for scripting and CI.
</ParamField>

Without `--template` or `--yes`, and when stdin is a TTY, `anvil init` prompts you to pick a template interactively.

## Templates

<CardGroup cols={3}>
  <Card title="basic" icon="folder-tree">
    A minimal REST API: one static route and one dynamic `[id]` route.
  </Card>

  <Card title="mcp" icon="plug">
    The same routes, with the dynamic route exposed as an MCP tool, plus a standalone tool in `server/tools/`.
  </Card>

  <Card title="agent" icon="robot">
    A streaming agent route at `/chat` using `MockDriver`, so it runs immediately with no API key.
  </Card>
</CardGroup>

## What it writes

<Steps>
  <Step title="package.json">
    If one doesn't exist, creates a minimal one with `"type": "module"`. If one exists, it's merged, not overwritten: `type` is forced to `"module"` (Anvil is ESM-only), the `dev`/`build`/`start`/`lint` scripts are added (your existing scripts are preserved and take precedence on name conflicts), and `anvil-sdk`/`zod` are added to `dependencies` — **without** clobbering a version you've already pinned for either.
  </Step>

  <Step title="tsconfig.json and .gitignore">
    Written only if missing. An existing file of either is left untouched.
  </Step>

  <Step title="Template route files">
    Each file the chosen template defines is written only if it doesn't already exist — `anvil init` never overwrites a file you've edited. Re-running `anvil init` in the same directory is safe; it reports what it skipped.
  </Step>
</Steps>

## Example: non-interactive, for scripting

```bash theme={null}
mkdir my-api && cd my-api
npx anvil init --template mcp
npm install
npx anvil mcp
```

## Example: adding Anvil to an existing project

Run `anvil init` in a directory that already has a `package.json` — it merges in the Anvil scripts and dependency instead of creating a new project:

```bash theme={null}
cd my-existing-app
npx anvil init -y
```

<Note>
  `anvil init` only writes files — it does not run `npm install` for you, and it doesn't assume a package manager. Run `npm install` (or your equivalent) yourself afterward.
</Note>

<Tip>
  Prefer the interactive prompt when you're not sure which template fits — it shows a one-line description of each before you choose.
</Tip>