Skip to main content
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

anvil init [dir] [options]
dir is the target directory. Defaults to the current directory. It’s created if it doesn’t exist.

​
Flags

​
-t, --template <name>
string
Template to scaffold: basic, mcp, or agent. Skips the interactive prompt.
​
-y, --yes
boolean
Skip the interactive prompt without specifying --template — defaults to the basic template. Useful for scripting and CI.
Without --template or --yes, and when stdin is a TTY, anvil init prompts you to pick a template interactively.

​
Templates

basic

A minimal REST API: one static route and one dynamic [id] route.

mcp

The same routes, with the dynamic route exposed as an MCP tool, plus a standalone tool in server/tools/.

agent

A streaming agent route at /chat using MockDriver, so it runs immediately with no API key.

​
What it writes

1

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/zod are added to dependencies — without clobbering a version you’ve already pinned for either.
2

tsconfig.json and .gitignore

Written only if missing. An existing file of either is left untouched.
3

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.

​
Example: non-interactive, for scripting

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: 
cd my-existing-app
npx anvil init -y
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.
Prefer the interactive prompt when you’re not sure which template fits — it shows a one-line description of each before you choose.