본문으로 건너뛰기
시작하기
제품요금제문서블로그로그인English시작하기

AiNecto CLI

AiNecto CLI는 저장소를 AiNecto 프로젝트와 연결해 역할별 Agent 세션을 준비하고, 터미널·스크립트·CI에서 같은 프로젝트 도구를 직접 실행합니다.

CLI(ainecto 명령)는 두 가지 일을 합니다.

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

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

실행하기​

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

npx -y ainecto@latest init

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

전역 설치가 필요하면: npm i -g ainecto.

세션 하나 = 역할 하나​

저장소의 세션은 역할 딱 하나로 일합니다.

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

역할은 한 곳에 저장됩니다 — init 이 저장소의 .mcp.json·.cursor/mcp.json 에 쓰는 ainecto 항목의 --role 입니다. 요청마다 함께 보내지고 서버가 적용합니다. 저장소에서 실행하는 ainecto 명령은 호출마다 이것을 읽으므로 새 역할을 바로 씁니다. 세션의 MCP 도구는 세션이 시작될 때의 역할(또는 역할 없음)을 그대로 가집니다. 모든 역할이 설계 전체를 읽을 수 있고, 역할 밖의 일이 필요하면 세션은 멈추고 어느 세션이 이어받아야 하는지 말합니다.

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

저장소 설정​

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

npx -y ainecto@latest init                     # 터미널: 역할과 프로젝트를 물어봄
npx -y ainecto@latest init --role development  # 에이전트·스크립트·CI: 아무것도 묻지 않음
  • 터미널에서는 주지 않은 것을 묻습니다: 역할(--role 이나 AINECTO_ROLE 이 없을 때, 번호로 고름 — 저장소에 이미 걸린 역할이 있을 때만 그것이 기본값이고, 저장소의 에이전트 설정이 서로 어긋나면 기본값이 없음)과 프로젝트(--project 가 없을 때, 번호로 고름, 새 프로젝트 만들기는 Design 에게만 나옴). 질문에서 Ctrl+C 나 Ctrl+D 를 누르면 저장소 파일을 쓰지 않고 취소합니다.
  • 에이전트나 CI 아래에서는(CLAUDECODE, CI, GEMINI_CLI, CODEX_SANDBOX, CURSOR_AGENT), 또는 입력·출력이 터미널이 아니면 아무것도 묻지 않습니다. --role 이 없으면 저장소에 이미 걸린 역할을 쓰고, 그것도 없으면(또는 저장소의 에이전트 설정이 서로 어긋나면) 사용자에게 역할을 물은 뒤 --role 로 다시 실행하라며 멈춥니다. 역할을 대신 고르지 않습니다.
  • 로그인까지 합니다. 이 컴퓨터가 아직 AiNecto 에 로그인하지 않았다면 init 이 로그인 URL 을 출력하고 브라우저를 열어, 승인하면 이어서 진행합니다 — 역할마다가 아니라 컴퓨터(서버) 마다 한 번입니다. 로그인은 5분이 지나면 포기합니다. 브라우저를 열 수 없으면 바로 실패합니다.
  • 프로젝트(터미널 밖). 계정에 프로젝트가 여러 개면 목록을 보여 주고 멈춥니다 — --project <uuid> 로 다시 실행하세요. 프로젝트가 하나도 없으면 Design 세션만 만들 수 있습니다(--yes, 원하면 --project-name <이름>). 다른 역할이면 프로젝트를 먼저 만든 뒤 같은 역할로 다시 실행하세요.
  • 저장소 루트. git 저장소의 하위 폴더에서 실행하면 멈추고 루트 위치를 알려 줍니다.
  • 다시 시작할 필요가 없습니다. init 직후 같은 세션에서 CLI 로 이어서 일합니다 — 저장소에서 실행하는 ainecto 명령은 그 역할을 바로 씁니다(.ainecto/HARNESS.md 를 읽고, ainecto tools list·ainecto tools call <도구> '<json>'). 이 일에 세션이 시작할 때 붙은 MCP 도구를 쓰지 마세요 — 그 도구는 세션이 시작될 때의 역할(또는 역할 없음)을 그대로 가집니다. 새 세션은 선택이고 그 역할의 MCP 도구만 더해 줍니다 — Claude Code 는 종료한 뒤 같은 폴더에서 claude -c 로 이어 가고, .mcp.json 의 ainecto 서버를 쓸지 물으면 승인합니다.

init 이 쓰는 파일:

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

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

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

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

에이전트에게 맡기기​

명령을 직접 치지 않아도 됩니다. 역할이 없는 AiNecto 세션이면 서버가 에이전트에게, 이 저장소의 세션이 가질 역할을 사용자에게 물으라고 안내합니다 — 에이전트가 스스로 고르면 안 됩니다. 에이전트는 답을 받아 npx -y ainecto@latest init --role <답한 역할> 을 대신 실행합니다. 사용자는 아직 로그인하지 않은 컴퓨터라면 브라우저에서 로그인을 승인합니다(로그인은 최대 5분 기다리므로 에이전트는 명령 제한 시간을 6분 이상 둡니다). init 이 프로젝트 목록을 보여 주면 에이전트가 어느 것인지 묻고 --project <uuid> 로 다시 실행합니다. 다시 시작할 필요는 없습니다 — 에이전트는 같은 세션에서 ainecto 명령으로 이어 갑니다. Claude Code 의 auto 모드가 npx 로 외부 패키지를 실행하는 것을 막으면 그 명령을 허용해 주세요.

직접 로그인하기​

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

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

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

자주 쓰는 명령​

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

역할은 저장소에서 옵니다. ainecto init 으로 설정한 폴더 안에서는(명령이 현재 폴더에서 위로 올라가며 ainecto 항목이 든 첫 .mcp.json/.cursor/mcp.json 을 찾습니다) 모든 명령이 그 폴더의 역할을 씁니다 — --role 을 주지 마세요. 그와 다른 --role 이나 AINECTO_ROLE 은 거절됩니다. 역할은 사용자에게 물은 뒤 ainecto init --role <역할> 로만 바꿉니다. 그 폴더의 역할을 읽을 수 없으면(올바른 --role 이 없는 @ainecto/mcp 항목, 서로 어긋난 설정, ainecto 를 담은 깨진 JSON, 폴더 밖을 가리키는 링크) 명령이 멈춥니다. 이 커넥터가 아닌 항목(예: HTTP url 항목)은 역할 없음으로 보고, 홈 폴더 자체는 저장소로 읽지 않습니다. 그런 폴더 밖에서는 역할이 없고(제한 없음), --role 을 주면 그 역할로 좁힙니다.

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

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

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

개발 환경에 붙기​

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

ainecto auth login --env dev
ainecto projects list --env dev

init 이 쓰는 MCP 커넥터​

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

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

이 컴퓨터의 로그인 하나를 쓰며, 스스로 브라우저를 열지 않습니다. 역할은 --role(또는 AINECTO_ROLE)에서만 오고 요청마다 함께 보내집니다. 역할 없는 커넥터는 제한이 없습니다. 설정한 저장소 안의 세션에 그래도 역할이 없으면 대개 다른 ainecto 항목(예: Claude Code 의 local scope)이 init 이 쓴 항목을 가리고 있는 것입니다 — claude mcp get ainecto 로 확인하세요. 다른 이름의 항목은 가리지는 않지만 역할 없는 두 번째 서버가 되므로 지우세요.

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

최종 수정: 에