Amplitude 마법사 CLI

Amplitude Wizard CLI(npx @amplitude/wizard)는 하나의 터미널 명령으로 기존 코드베이스에 Amplitude 애널리틱스를 설치합니다. 이 도구는 사용자의 프레임워크를 감지하고, 실제 코드를 기반으로 이벤트 추적을 제안하며, 모든 단계에서 사용자의 승인을 받아 한 세션에 SDK 연동을 작성합니다.

AI 에이전트가 코드베이스를 읽고 한 세션 내에 사용자를 위해 이벤트를 구현하도록 하려면 마법사를 사용하십시오. 이벤트를 직접 선택하고 SDK 호출을 직접 작성하려는 경우, 대신 Amplitude 빠른 시작을 따르십시오.

npx @amplitude/wizard

마법사는 터미널에서 실행됩니다. Amplitude는 터미널에서 Claude Code를 테스트하고 있으며, Claude Code Desktop, Cursor Desktop 등은 현재 개발 중입니다. 하위 명령 및 옵션에 대한 자세한 내용을 확인하려면 npx @amplitude/wizard --help를 실행하세요.

Amplitude Wizard CLI를 실행할 때 수행하는 작업

1. 인증: 마법사가 사용자를 로그인(또는 기존 세션을 선택)하고 조직, 프로젝트 및 데이터 영역을 선택할 수 있도록 합니다.
2. 프레임워크 감지: 마법사는 프로젝트를 검사하고 올바른 연동 경로를 선택합니다. 자동 감지 기능은 Next.js, Vue, React Router, Django, Flask, FastAPI, Swift, React Native, Android, Flutter, Go, Java, Unreal 및 Unity를 지원하며, JavaScript(웹), Python 및 JavaScript(노드)에 대해서는 언어 수준의 대체 기능을 제공합니다. 일치하는 항목이 없으면 수동으로 선택하거나 일반 대체 기능을 사용할 수 있습니다. 웹 프로젝트는 Browser SDK 2 또는 Browser Unified SDK를 사용합니다.
3. 이벤트 제안 및 계측: Amplitude AI 에이전트는 코드베이스를 읽고, 앱의 기능을 기반으로 이벤트 추적을 제안하며, 전체 코드를 작성하기 전에 사용자의 승인을 기다립니다. 본인의 에이전트 라이선스는 필요하지 않습니다.
4. MCP 연동 설정: 마법사는 Amplitude MCP 서버를 편집기에 설치하도록 제안해 주므로 평범한 영어로 분석 데이터를 쿼리할 수 있습니다.
5. 확인: 마법사는 도착하는 이벤트를 감지할 때까지 Amplitude API를 폴링합니다. 앱을 실행하고 몇 가지 작업을 트리거하면 마법사가 유입되는 이벤트를 실시간으로 보여줍니다.
6. 차트 및 대시보드 생성: 에이전트는 Amplitude에서 첫 번째 대시보드를 구축하므로 데이터가 흐르기 시작하는 순간부터 유용한 정보를 얻을 수 있습니다.

Ctrl+C를 눌러 마법사를 중지하거나, 마법사가 충돌하거나, 터미널을 닫으면 마법사가 체크포인트를 저장합니다. 재개하려면 동일한 디렉토리에서 다시 실행하십시오.

이미 사용하고 있는 도구에서 Amplitude 데이터에 액세스하세요

• 터미널 또는 IDE: Amplitude MCP 서버를 사용하여 Claude, Cursor 또는 전체 MCP 호환 AI 도구에서 데이터에 대해 평범한 영어로 질문하세요. 에이전트는 --agent 모드를 사용하여 CLI를 실행할 수 있습니다.

• Claude Code 플러그인: Claude Code용 Amplitude 플러그인을 설치하세요. 이 플러그인은 동일한 MCP 도구와 함께 빠른 액세스를 위한 내장 슬래시 명령을 제공합니다.

  Claude Code 세션 내에서:

  bash

  복사

  /plugin install amplitude
  

  또는 터미널에서:

  bash

  복사

  claude plugin install amplitude
  

  설치 후, Claude Code에서 /mcp를 실행하고 브라우저 프롬프트에 따라 Amplitude에 로그인하세요. 이 플러그인에는 /amplitude:create-chart, /amplitude:create-dashboard, /amplitude:instrument-events, /amplitude:replay-ux-audit, /amplitude:weekly-brief 등의 슬래시 명령이 포함되어 있습니다.

• Slack 또는 Teams 앱: Amplitude를 팀의 메시징 도구에 연결하여 업무 환경에서 인사이트를 얻고, 차트를 만들 수 있는 등의 작업을 수행하세요.

AI 에이전트에서 Amplitude Wizard CLI 실행

AI 코딩 에이전트는 마법사를 처음부터 끝까지 직접 제어할 수 있습니다. --agent 모드는 NDJSON 생애주기 분석 이벤트를 표준 출력(한 줄에 하나의 JSON 객체, 각 객체에 v:1 엔벨로프)으로 스트리밍하므로, 오케스트레이터는 진행 상황, 파일 차이점 및 프롬프트를 실시간으로 렌더링할 수 있습니다. 이는 마법사의 프롬프트를 자동으로 승인합니다.

사람을 건너뛰는 올바른 방법은 사용자가 이미 Amplitude 계정을 가지고 있는지 여부에 따라 다릅니다.

Amplitude 신규 계정입니다. --auth-onboarding create-account와 사용자 정보를 전달하면 마법사가 조직, 프로젝트 및 앱을 프로비저닝합니다. --api-key는 완전히 건너뛰세요. 마법사는 계정 생성 과정의 일환으로 하나를 생성합니다. create-account과 --agent를 결합할 때 --email, --full-name, --accept-tos 및 --region은 모두 필요합니다. 마법사에는 이를 요청할 TTY가 없기 때문입니다.

npx @amplitude/wizard --agent \
  --auth-onboarding create-account \
  --email <new-account-email> \
  --full-name "<Full Name>" \
  --accept-tos \
  --region <us|eu> \
  --app-name "<app name>" \
  -y

--agent은 이미 --auto-approve를 의미합니다. 내부 에이전트에 쓰기 권한을 부여하려면 -y이 여전히 필요합니다.

기존 Amplitude 계정으로, 완전히 무인입니다. 마법사가 OAuth를 건너뛸 수 있도록 Amplitude 프로젝트 API 키를 인라인으로 전달하십시오. 실행을 특정 Amplitude 앱에 바인딩하려면 --app-id <id>를 추가하십시오. 마법사가 조직, 프로젝트 및 환경을 자동으로 파생하므로 에이전트에게 필요한 유일한 범위 플래그입니다:

npx @amplitude/wizard --agent --install-dir . --api-key <key> --app-id <id>

기존 Amplitude 계정, 동일한 컴퓨터에 이전 로그인. 일회성 npx @amplitude/wizard login 실행 후에는 --api-key을 생략할 수 있으며, 마법사는 저장된 OAuth 토큰을 재사용합니다.

키 플래그

npx @amplitude/wizard manifest을 실행하여 기계 판독 가능한 전체 CLI 표면(플래그, 환경 변수, 종료 코드 및 용어집)을 JSON 형식으로 출력하십시오.

계획, 적용 및 검증

차이점 분석에 사람이 참여하기를 원하는 에이전트의 경우 실행을 세 단계로 나누십시오. plan과 verify는 디스크에 절대 접근하지 않습니다.

npx @amplitude/wizard plan --json
npx @amplitude/wizard apply --plan-id <id> --yes
npx @amplitude/wizard verify --json

1. plan --json는 감지된 프레임워크, SDK 선택 사항 및 의도된 파일 변경 사항이 포함된 WizardPlan를 생성한 다음 24시간 동안 유효한 planId를 반환합니다. 출력에는 바로 실행 가능한 resumeFlags 배열도 포함됩니다. 이 배열을 apply에 바로 입력하십시오.
2. apply --plan-id <id> --yes는 계획을 실행하고 모든 쓰기 작업에 대해 NDJSON file_change 이벤트를 스트리밍합니다. 파괴적인 덮어쓰기를 허용하려면 --force를 추가하십시오.
3. verify --json는 SDK, API 키 및 프레임워크 연동이 모두 제대로 설정되었는지 확인하는 저렴하고 네트워크 연결이 필요 없는 검사를 실행합니다. 실패 시 0이 아닌 종료 코드를 반환합니다.

에이전트 친화적인 다른 하위 명령에는 다른 스크립트에서 저장된 OAuth 토큰을 읽기 위한 detect --json, status --json, auth status --json, auth token가 있습니다.

MCP 서버 모드

npx @amplitude/wizard mcp serve는 마법사의 읽기 전용 작업을 stdio를 통해 모델 컨텍스트 프로토콜 도구로 노출합니다. AI 에이전트는 CLI를 생성하고 출력을 파싱하는 대신 이를 타입이 지정된 도구로 호출합니다. 이 코드를 MCP 클라이언트의 구성에 추가하십시오.

{
  "mcpServers": {
    "amplitude-wizard": {
      "command": "npx",
      "args": ["-y", "@amplitude/wizard", "mcp", "serve"]
    }
  }
}

서버는 detect_framework, get_project_status, plan_setup, verify_setup, get_auth_status, 및 get_auth_token를 노출시킵니다. plan_setup을 apply CLI 하위 명령과 페어링하여 결과 계획을 실행하십시오.

환경 변수

마법사는 --agent 실행 시 다음 변수를 읽습니다.

종료 코드

오케스트레이터는 마법사의 종료 코드에 따라 분기할 수 있습니다.

종료 코드 3(AUTH_REQUIRED)는 오케스트레이터에게 중요한 신호입니다. 마법사는 유효한 자격 증명 없이 --agent 실행이 시작될 때 이 코드를 발생시키며, 구조화된 lifecycle NDJSON 이벤트도 함께 전송합니다. 이 이벤트의 data.loginCommand 및 data.resumeCommand 배열은 오케스트레이터에게 사용자에게 로그인하고 다시 실행하도록 안내하는 방법을 정확하게 알려줍니다. 이유 값에는 no_stored_credentials, token_expired, refresh_failed, env_selection_failed이 포함됩니다.

{
  "v": 1,
  "type": "lifecycle",
  "level": "error",
  "data": {
    "event": "auth_required",
    "reason": "no_stored_credentials",
    "loginCommand": ["npx", "@amplitude/wizard", "login"],
    "resumeCommand": ["npx", "@amplitude/wizard", "--agent"]
  }
}

no_stored_credentials에서 loginCommand를 노출하는 대신, 새로운 계정 플래그(--auth-onboarding create-account 및 --email, --full-name, --accept-tos, --region, --app-name)를 사용하여 다시 호출하고 새 계정을 인라인으로 생성하는 방법도 있습니다. 이 경로는 --accept-tos와 --region에서 여전히 명시적인 사용자 입력이 필요하기 때문에 제로 프롬프트(zero-prompt)는 아니지만, 브라우저 기반의 OAuth 핸드셰이크 단계는 건너뜁니다.

데이터가 흐르는 후에 시도해야 할 일

• 첫 번째 세션 리플레이 보기: 사용자가 앱에서 무엇을 경험하는지 정확하게 검토하세요.
• 웹 실험 시작: 비주얼 편집기를 사용하여 추가 코드 없이 기능을 A/B로 테스트하세요.
• 가이드 또는 설문조사 생성: 제품 내 피드백을 수집하거나 특정 사용자 세그먼트에게 메시지를 표시합니다.

피드백

이 마법사는 오픈 소스입니다. 소스를 보고, 문제를 리포트하고, GitHub에 기여하십시오.

현재 잘 작동하는 부분과 향후 원하는 기능을 wizard@amplitude.com으로 공유해 주십시오.