AI-ERD CLI

CLI(ai-erd 명령)는 두 가지 일을 합니다.

하네스 — ai-erd init 이 저장소를 AI-ERD 프로젝트에 붙여, 그 저장소의 AI 코딩 세션마다 역할을 딱 하나만 갖게 합니다.
직접 호출 — AI 어시스턴트가 쓰는 것과 같은 도구를 터미널·셸 스크립트·CI 에서 부릅니다. 중간에 AI 클라이언트가 없습니다.

CLI 와 MCP 중 무엇을? MCP 는 AI 어시스턴트를 연결해 말로 시키는 방식입니다. CLI 는 그 연결을 저장소마다 설정해 주고, 사람이 직접 몰 때 도 씁니다 — 스크립트로 내보내기, CI 검사, 한 번씩 조회하기. 둘은 같은 서버를 봅니다.

실행하기

전역 설치는 필요 없습니다. 저장소 루트에서 npx 로 최신 판을 바로 실행합니다.

npx -y ai-erd@latest init

Node.js 18 이상이 필요합니다.

전역 설치가 필요하면 ai-erd 하나만 설치하세요: npm i -g ai-erd.

세션 하나 = 역할 하나

세션은 역할을 정확히 하나 골라 끝까지 유지합니다.

역할	맡는 것	하지 않는 것
`design`	요구사항, ERD, 도메인·모듈 경계, 의존 방향, 태스크	제품 코드·테스트 코드 작성
`development`	승인된 설계를 따르는 제품 코드	요구사항·ERD·아키텍처·데이터 소유권 변경
`test`	테스트 시나리오와 테스트 코드, 실행과 결과 확인	테스트를 통과시키려고 제품 코드 수정, 설계 변경
`validation`	결과를 설계와 규칙에 비추어 판정	무엇이든 변경 — 근거와 함께 PASS 또는 FAIL 만 보고

역할은 한 곳에 저장됩니다 — init 이 저장소의 .mcp.json·.cursor/mcp.json 에 쓰는 ai-erd 항목의 --role 입니다. 요청마다 함께 보내지고 서버가 적용합니다. 세션 도중에는 바뀌지 않습니다 — 새 세션이 시작될 때까지 서버는 그 역할의 도구만 보여 줍니다. 모든 역할이 설계 전체를 읽을 수 있고, 역할 밖의 일이 필요하면 세션은 멈추고 어느 세션이 이어받아야 하는지 말합니다.

역할은 작업 가드레일이지 보안 경계가 아닙니다 — 로그인은 역할 없이 한 번 하고, init 으로 설정한 폴더 밖에서는 역할도 제한도 없습니다.

저장소 설정

저장소 루트에서 실행합니다.

npx -y ai-erd@latest init                     # 터미널: 역할과 프로젝트를 물어봄
npx -y ai-erd@latest init --role development  # 에이전트·스크립트·CI: 아무것도 묻지 않음

터미널에서는 주지 않은 것을 묻습니다: 역할(번호로 고름 — 저장소에 이미 걸린 역할이 있으면 그것이 기본값)과 프로젝트(번호로 고름, 새 프로젝트 만들기는 Design 에게만 나옴). 질문에서 Ctrl+C 나 Ctrl+D 를 누르면 저장소 파일을 쓰지 않고 취소합니다.
에이전트나 CI 아래에서는(CLAUDECODE, CI, GEMINI_CLI, CODEX_SANDBOX, CURSOR_AGENT), 또는 입력·출력이 터미널이 아니면 아무것도 묻지 않습니다. --role 이 없으면 저장소에 이미 걸린 역할을 쓰고, 그것도 없으면 사용자에게 역할을 물은 뒤 --role 로 다시 실행하라며 멈춥니다. 역할을 대신 고르지 않습니다.
로그인까지 합니다. 이 컴퓨터가 아직 AI-ERD 에 로그인하지 않았다면 init 이 로그인 URL 을 출력하고 브라우저를 열어, 승인하면 이어서 진행합니다 — 역할마다가 아니라 컴퓨터(서버) 마다 한 번입니다. 로그인은 5분이 지나면 포기합니다. 브라우저를 열 수 없으면 바로 실패합니다.
프로젝트(터미널 밖). 계정에 프로젝트가 여러 개면 목록을 보여 주고 멈춥니다 — --project <uuid> 로 다시 실행하세요. 프로젝트가 하나도 없으면 Design 세션만 만들 수 있습니다(--yes, 원하면 --project-name <이름>). 다른 역할이면 프로젝트를 먼저 만든 뒤 같은 역할로 다시 실행하세요.
저장소 루트. git 저장소의 하위 폴더에서 실행하면 멈추고 루트 위치를 알려 줍니다.
역할은 새 세션부터 적용됩니다. 실행 중인 세션은 시작할 때의 역할을 그대로 가집니다. init 이 다시 시작하는 방법을 알려 줍니다 — Claude Code 는 종료한 뒤 같은 폴더에서 claude -c 로 이어 가고, .mcp.json 의 ai-erd 서버를 쓸지 물으면 승인합니다.

init 이 쓰는 파일:

파일	용도
`.mcp.json`	Claude Code — `--role` 이 붙은 `ai-erd` MCP 서버 항목 하나
`.cursor/mcp.json`	Cursor — 같은 항목 하나
`AGENTS.md`	관리되는 짧은 블록 (파일이 없으면 만듦)
`CLAUDE.md`	같은 블록 — 파일이 이미 있을 때만
`.ai-erd/HARNESS.md`	이 프로젝트의 하네스 규칙
`.ai-erd/config.json`, `.ai-erd/init-record.json`	연결된 프로젝트, 그리고 `--undo` 가 쓰는 기록

서버 항목은 일부러 하나만 씁니다 — 네 역할을 한꺼번에 등록하면 development 세션이 다시 design 도구를 보게 되기 때문입니다. 역할을 바꾸려면 다른 --role 로 init 을 다시 실행하고 새 세션을 여세요.

Codex 는 전역 설정 하나만 쓰므로 init 이 건드리지 않습니다. 대신 $CODEX_HOME/<역할>.config.toml 로 저장할 프로필을 출력하고, 세션은 codex -p <역할> 로 시작합니다.

npx -y ai-erd@latest init --role design --dry-run   # 무엇이 바뀔지 보여 주기만
npx -y ai-erd@latest init --undo                    # init 이 쓴 것을 되돌림

에이전트에게 맡기기

명령을 직접 치지 않아도 됩니다. 역할이 없는 AI-ERD 세션이면 서버가 에이전트에게, 이 저장소의 세션이 가질 역할을 사용자에게 물으라고 안내합니다 — 에이전트가 스스로 고르면 안 됩니다. 에이전트는 답을 받아 npx -y ai-erd@latest init --role <답한 역할> 을 대신 실행합니다. 사용자는 아직 로그인하지 않은 컴퓨터라면 브라우저에서 로그인을 승인하고, 끝나면 세션을 다시 시작합니다.

직접 로그인하기

init 이 필요할 때 로그인까지 하므로 보통은 건너뜁니다. 로그인을 직접 관리하려면:

ai-erd auth login     # 컴퓨터마다(그리고 --env 마다) 한 번, 역할마다가 아님
ai-erd auth status    # 로그인이 살아 있는지
ai-erd auth logout    # 이 컴퓨터의 로그인 삭제

로그인에는 역할이 없습니다 — 역할은 저장소에서 옵니다(아래 참고).

자주 쓰는 명령

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

역할은 저장소에서 옵니다. ai-erd init 으로 설정한 폴더 안에서는(명령이 현재 폴더에서 위로 올라가며 ai-erd 항목이 든 첫 .mcp.json/.cursor/mcp.json 을 찾습니다) 모든 명령이 그 폴더의 역할을 씁니다 — --role 을 주지 마세요. 그와 다른 --role 이나 AI_ERD_ROLE 은 거절됩니다. 역할은 사용자에게 물은 뒤 ai-erd init --role <역할> 로만 바꿉니다. 그 폴더의 역할을 읽을 수 없으면(--role 없는 ai-erd 항목, 서로 어긋난 설정, 폴더 밖을 가리키는 링크) 명령이 멈춥니다. 그런 폴더 밖에서는 역할이 없고(제한 없음), --role 을 주면 그 역할로 좁힙니다.

여기 쓰는 도구 이름은 서버가 내보내는 이름입니다 — 도구 레퍼런스 의 prefix 없는 snake_case 이름 그대로입니다. mcp__ai-erd__… 앞부분은 AI 클라이언트가 붙이는 것이고, CLI 는 서버에 직접 말하므로 쓰지 않습니다.

큰 페이로드는 명령줄 대신 파일이나 stdin 으로 줄 수 있습니다.

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

개발 환경에 붙기

모든 명령에 --env dev 를 붙이면 운영(https://ai-erd.com/mcp) 대신 dev.ai-erd.com 을 봅니다. 로그인은 환경별로 따로 합니다.

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

`init` 이 쓰는 MCP 커넥터

같은 패키지가 stdio↔HTTP 프록시 역할도 합니다. init 이 .mcp.json 에 쓰는 항목이 이것이고, 보통 손으로 넣지 않습니다.

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

이 컴퓨터의 로그인 하나를 쓰며, 스스로 브라우저를 열지 않습니다. 역할은 --role(또는 AI_ERD_ROLE)에서만 오고 요청마다 함께 보내집니다. 역할 없는 커넥터는 제한이 없습니다 — .mcp.json 이 역할을 정한 폴더 안에서 역할 없이 뜨면 경고 한 줄을 출력합니다. 대개 다른 ai-erd 항목이 init 이 쓴 항목을 가리고 있는 것입니다(claude mcp get ai-erd).

init 하지 않은 저장소에서도 AI-ERD 를 쓰려면 클라이언트를 HTTP 로 https://ai-erd.com/mcp 에 연결하세요 — Claude Code 라면 user scope 로 (claude mcp add --scope user …, Claude Code 참고). local scope 로 넣으면 init 이 쓴 .mcp.json 을 가려서 저장소의 역할이 영영 적용되지 않습니다.

옛 패키지 이름

CLI 는 예전에 @ainecto/mcp 로 배포됐습니다. 그 패키지는 0.3.0 에서 deprecate 되어 더 이상 릴리스를 받지 않습니다 — 지우고 ai-erd 를 쓰세요.

실행하기​

세션 하나 = 역할 하나​

저장소 설정​

에이전트에게 맡기기​

직접 로그인하기​

자주 쓰는 명령​

개발 환경에 붙기​

init 이 쓰는 MCP 커넥터​

옛 패키지 이름​