AI-ERD CLI

The CLI (the ai-erd command) does two jobs:

Harness — ai-erd init wires a repository to an AI-ERD project so each AI coding session in it runs in exactly one role.
Direct calls — the same tools your AI assistant uses, from your terminal, a shell script, or CI. No AI client in the loop.

CLI or MCP? MCP connects an AI assistant so you can ask for changes in plain language. The CLI sets that connection up per repository, and is also for when you are the one driving: scripted exports, CI checks, one-off queries. Both talk to the same server.

Run it

No global install is needed. Run the latest version through npx, from your repository root:

npx -y ai-erd@latest init

Requires Node.js 18 or newer.

If you need a global install, install ai-erd only: npm i -g ai-erd.

One session, one role

A session picks exactly one role and keeps it for the whole session.

Role	Owns	Must not
`design`	Requirements, ERD, domain and module boundaries, dependency direction, tasks	Write product or test code
`development`	Product code, following the approved design	Change requirements, ERD, architecture, or data ownership
`test`	Test scenarios and test code, running them and reading results	Change product code to make a test pass; change the design
`validation`	Judging the result against the design and the rules	Change anything; it reports PASS or FAIL with evidence

The role is stored in one place: the ai-erd entry that init writes into the repository's .mcp.json and .cursor/mcp.json (its --role). It is sent with every request and the server applies it. It does not change during a session: the server exposes only that role's tools until a new session starts. Every role can read the whole design; when the work needs something the role cannot do, the session stops and says which session should pick it up.

Roles are a working guardrail, not a security boundary — you sign in once, without a role, and outside a folder set up with init there is no role and no restriction.

Set up a repository

Run this from the repository root:

npx -y ai-erd@latest init                     # in a terminal: asks for the role and the project
npx -y ai-erd@latest init --role development  # agents, scripts, CI: nothing is asked

In a terminal, init asks for what you did not pass: the role (by number — the role already set on the repository is the default, if there is one) and the project (by number; creating a new project is offered to Design only). Ctrl+C or Ctrl+D at a question cancels without writing repository files.
Under an agent or CI (CLAUDECODE, CI, GEMINI_CLI, CODEX_SANDBOX, CURSOR_AGENT), or when input or output is not a terminal, it asks nothing. Without --role it uses the role already set on the repository; if there is none, it stops and says to ask the user, then re-run with --role. It never picks a role for you.
Sign-in is included. If this machine is not signed in to AI-ERD yet, init prints the sign-in URL, opens a browser, and continues once you approve — once per machine (per server), not per role. Sign-in gives up after 5 minutes. It fails at once if the browser cannot be opened.
Projects (outside a terminal). If your account has more than one project, init lists them and stops; re-run with --project <uuid>. With no project yet, only a Design session can create one (--yes, optionally --project-name <name>); in any other role, create the project first, then re-run with the same role.
Repository root. Run from a sub-folder of a git repository and init stops and tells you the root.
The role applies from a new session. The running session keeps the role it started with. init tells you how to restart: in Claude Code, exit and run claude -c in the same folder, then approve the ai-erd server from .mcp.json when asked.

init writes:

File	For
`.mcp.json`	Claude Code — one `ai-erd` MCP server entry carrying `--role`
`.cursor/mcp.json`	Cursor — the same single entry
`AGENTS.md`	A short managed block (the file is created if missing)
`CLAUDE.md`	The same block, only if the file already exists
`.ai-erd/HARNESS.md`	The harness rules for this project
`.ai-erd/config.json`, `.ai-erd/init-record.json`	The bound project, and the record `--undo` uses

Only one server entry is written, on purpose — registering all four roles at once would let a development session see the design tools again. To switch roles, re-run init with another --role and start a new session.

Codex keeps a single global config, so init does not touch it. It prints a profile to save as $CODEX_HOME/<role>.config.toml; start the session with codex -p <role>.

npx -y ai-erd@latest init --role design --dry-run   # show what would change
npx -y ai-erd@latest init --undo                    # remove what init wrote

Letting your agent do it

You do not have to type the command yourself. When an AI-ERD session has no role, the server tells the agent to ask you which role this repository's sessions should have — it must not choose one itself — and then to run npx -y ai-erd@latest init --role <your answer> for you. If this machine is not signed in yet, you approve the sign-in in the browser, and restart the session when it is done.

init signs in when it needs to, so you normally skip this. To manage the sign-in yourself:

ai-erd auth login     # once per machine (and per --env); not per role
ai-erd auth status    # is the sign-in still good?
ai-erd auth logout    # forget the sign-in on this machine

Sign-in has no role — the role comes from the repository (see below).

Everyday commands

ai-erd projects list
ai-erd tools list
ai-erd tools call list_projects --json
ai-erd erd apply-changes -f erd-operations.json --yes

The role comes from the repository. Inside a folder set up with ai-erd init (the command looks from the current folder upward for the first .mcp.json / .cursor/mcp.json with an ai-erd entry), every command uses that folder's role — do not pass --role. A --role or AI_ERD_ROLE that differs from it is refused; the role changes only with ai-erd init --role <role>, after asking the user. If the role there cannot be read (an ai-erd entry without --role, configs that disagree, a link that points outside the folder), the command stops. Outside such a folder there is no role (no restriction), and --role narrows it.

Tool names here are the ones the server publishes — the plain snake_case names from the tool reference, with no client prefix. That prefix (mcp__ai-erd__…) is something your AI client adds; the CLI talks to the server directly and does not use it.

Large payloads can come from a file or stdin instead of the command line:

ai-erd tools call erd_apply_changes -f changes.json --json
cat payload.json | ai-erd tools call erd_apply_changes --json

Talking to the dev environment

Every command takes --env dev to point at dev.ai-erd.com instead of production (https://ai-erd.com/mcp). Sign-in is per environment:

ai-erd auth login --env dev
ai-erd projects list --env dev

The MCP connector `init` writes

The same package doubles as a stdio-to-HTTP proxy. This is the entry init writes into .mcp.json — you normally do not add it by hand:

{
  "mcpServers": {
    "ai-erd": {
      "command": "npx",
      "args": ["-y", "@ai-erd/mcp", "--role", "development"]
    }
  }
}

It uses this machine's one sign-in and never opens a browser on its own. Its role comes only from --role (or AI_ERD_ROLE) and is sent with every request. A connector without a role has no restriction; if it starts inside a folder whose .mcp.json sets a role, it prints a one-line warning — usually another ai-erd entry is hiding the one init wrote (claude mcp get ai-erd).

To use AI-ERD outside an init-ed repository, connect your client over HTTP to https://ai-erd.com/mcp — in Claude Code at user scope (claude mcp add --scope user …, see Claude Code). A local-scope entry would hide the .mcp.json that init writes, and the repository's role would never apply.

Old package name

The CLI used to be published as @ainecto/mcp. That package was deprecated at 0.3.0 and receives no further releases — uninstall it and use ai-erd.

Run it​

One session, one role​

Set up a repository​

Letting your agent do it​

Sign in manually​

Everyday commands​

Talking to the dev environment​

The MCP connector init writes​

Old package name​