CLI 설치와 로그인

CLI를 설치하고 로그인하면 에이전트가 규격을 읽고 컨트롤러와 게임 빌드를 업로드합니다. 별도 SDK 설치나 MCP 등록은 필요하지 않습니다.

1. 설치와 규격 확인

Node.js 24 LTS를 준비하고 실행하세요.

npm install -g @immercy/cli
immercy help

프로젝트 안에만 설치하려면 npm install --save-dev @immercy/cli 후 npx immercy로 실행하세요.

2. API Key로 로그인

대시보드에서 프로젝트를 만들고 발급받은 API Key를 준비하세요. 게임 폴더의 터미널에서 실행하고 키를 입력합니다.

immercy login

키는 화면에 표시되지 않습니다. CLI가 프로젝트 ID를 조회하고 immercy.config.json을 생성합니다. 키는 .immercy.local.json에 저장하고 Git 제외 설정을 자동으로 추가합니다. 기존 프로젝트와 다른 키는 덮어쓰지 않습니다.

키를 재발급했다면 다시 로그인하세요. API Key를 에이전트 대화에 붙여 넣을 필요가 없습니다.

3. 에이전트에게 맡기기

immercy help를 읽고 immercy project --json으로 프로젝트를 확인해 줘.
immercy init으로 파일을 준비해 줘.
왼쪽 이동 조이스틱과 오른쪽 점프 버튼이 있는 컨트롤러를 만들고 CLI로 검증해서 업로드해 줘.

에이전트 작업 흐름에서 게임 제작과 배포 요청도 확인할 수 있습니다.

4. 프리뷰 확인과 출시

immercy preview는 게임·컨트롤러 프리뷰 주소와 현재 출시 상태를 보여 줍니다. 브라우저에서 소유자 계정으로 로그인하고 실제 플레이를 확인하세요.

immercy release로 출시 상태를 조회하고, 준비가 끝나면 immercy release --visibility unlisted로 링크 공개하거나 --visibility public으로 전체 공개를 요청할 수 있습니다. 전체 공개는 검토 승인 후 다른 사용자가 플레이할 수 있습니다. 출시와 공유에서 공개 범위와 공유 절차를 확인하세요.

CI와 다른 서버

CI는 비밀 환경 변수 IMMERCY_API_KEY를 사용할 수 있습니다. 이 값은 로컬 로그인보다 우선합니다. 표준입력으로 키 하나를 전달하려면 immercy login --key-stdin을 사용하세요. 명령 인자에 키를 쓰는 옵션은 제공하지 않습니다.

로컬 플랫폼은 immercy login --origin http://localhost:3000으로 연결합니다. 일반 서버는 HTTPS origin만 허용합니다. --config <상대 경로>로 별도 설정 파일을 선택할 수 있습니다.

패키지 공개 전 확인

레지스트리 설치에는 운영자의 npm 게시가 필요합니다. 저장소 개발자는 루트에서 npm ci와 npm pack --workspace @immercy/cli를 실행한 뒤 출력된 tarball 경로로 npm install -g <tarball 경로>를 실행해 같은 흐름을 확인할 수 있습니다. SDK 패키지를 먼저 게시할 필요는 없습니다.