AiNecto CLI

The CLI (the ainecto command) does two jobs:

Harness — ainecto init wires a repository to an AiNecto 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 ainecto@latest init

Requires Node.js 18 or newer.

If you need a global install: npm i -g ainecto.

One session, one role

A repository's sessions work in exactly one role.

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 ainecto 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. ainecto commands run in the repository read it on every call, so they use a new role at once; a session's MCP tools keep the role (or no role) the session started with. 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 ainecto@latest init                     # in a terminal: asks for the role and the project
npx -y ainecto@latest init --role development  # agents, scripts, CI: nothing is asked

In a terminal, init asks for what you did not pass: the role, unless --role or AINECTO_ROLE is set (by number — the role already set on the repository is the default only when there is one; if its agent configs disagree, there is no default) and the project, unless --project is set (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 (or the repository's agent configs disagree), 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 AiNecto 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.
No restart is needed. Right after init, keep working in the same session through the CLI: ainecto commands run from the repository use its role at once (read .ainecto/HARNESS.md, then ainecto tools list and ainecto tools call <tool> '<json>'). Do not use the MCP tools the session started with for that work — they keep the role (or no role) the session started with. A new session is optional and only adds the role's MCP tools: in Claude Code, exit and run claude -c in the same folder, then approve the ainecto server from .mcp.json when asked.

init writes:

File	For
`.mcp.json`	Claude Code — one `ainecto` 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
`.ainecto/HARNESS.md`	The harness rules for this project
`.ainecto/config.json`, `.ainecto/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 (after asking the user). ainecto commands use the new role at once; MCP tools pick it up in 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; to get the role's MCP tools, start a session with codex -p <role>.

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

Letting your agent do it

You do not have to type the command yourself. When an AiNecto 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 ainecto@latest init --role <your answer> for you. If this machine is not signed in yet, you approve the sign-in in the browser (the agent should allow the command at least 6 minutes — sign-in waits up to 5). If init lists projects, the agent asks you which one and re-runs with --project <uuid>. No restart is needed: the agent keeps working in the same session through ainecto commands. Claude Code's auto mode may block running a package with npx; if it does, allow the command.

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

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

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

Everyday commands

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

The role comes from the repository. Inside a folder set up with ainecto init (the command looks from the current folder upward for the first .mcp.json / .cursor/mcp.json with an ainecto entry), every command uses that folder's role — do not pass --role. A --role or AINECTO_ROLE that differs from it is refused; the role changes only with ainecto init --role <role>, after asking the user. If the role there cannot be read (the @ainecto/mcp entry without a valid --role, configs that disagree, broken JSON that mentions ainecto, a link that points outside the folder), the command stops. An entry that is not this connector (for example an HTTP url entry) means no role there, and your home folder itself is never read as a repository. 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__ainecto__…) is something your AI client adds; the CLI talks to the server directly and does not use it (a name that still carries the mcp__ainecto__ prefix is accepted).

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

ainecto tools call erd_apply_changes -f changes.json --json
cat payload.json | ainecto tools call erd_apply_changes --json

Talking to the dev environment

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

ainecto auth login --env dev
ainecto 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": {
    "ainecto": {
      "command": "npx",
      "args": ["-y", "@ainecto/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 AINECTO_ROLE) and is sent with every request. A connector without a role has no restriction. If a session inside a set-up repository still has no role, another ainecto entry (for example Claude Code's local scope) is usually hiding the one init wrote — check with claude mcp get ainecto. An entry under another name does not hide it but adds a second server with no role — remove it.

To use AiNecto outside an init-ed repository, connect your client over HTTP to https://ainecto.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.

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​