Amplitude ウィザード CLI

Amplitude Wizard CLI（npx @amplitude/wizard）は、1つのターミナルコマンドからAmplitude Analyticsを既存のコードベースにインストールします。フレームワークを検出し、実際のコードに基づいてイベントを追跡することを提案し、すべてのステップであなたの承認を得て、1つのセッションでSDK連携を記述します。

1つのセッションでAIエージェントにコードベースを読み取らせ、イベントを計測させたい場合に、このウィザードを使用します。イベントを手作業で選択して自分でSDK呼び出しを記述したい場合は、代わりにAmplitudeクイックスタートに従ってください。

npx @amplitude/wizard

このウィザードはターミナルで実行されます。 Amplitudeは、Claude Code Desktop、Cursor Desktopなどを開発中で、ターミナルでClaude Codeをテストしています。サブコマンドやオプションに関する情報は、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（web）、Python、JavaScript（Node）の言語レベルのフォールバック機能も備えています。一致するものが何もない場合は、手動で選択するか、汎用フォールバックを使用できます。 Webプロジェクトでは、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ウィザードCLIを実行する

--agent``v:1AIコーディングエージェントはウィザードをエンドツーエンドで駆動できます。モードはNDJSONライフサイクルイベントをstdoutにストリーミングします（1行あたり1つのJSONオブジェクト、それぞれにエンベロープがあります）。そのため、オーケストレーターは進行状況、ファイル差分、プロンプトをリアルタイムでレンダリングできます。ウィザードのプロンプトが自動的に承認されます。

人間をスキップする正しい方法は、ユーザーがすでにAmplitudeアカウントを持っているかどうかによって異なります。

Amplitudeの新しいアカウントです。 --auth-onboarding create-accountとユーザーの詳細情報を渡すことで、ウィザードがユーザーのために組織、プロジェクト、およびアプリのプロビジョニングを行います。 --api-keyを完全にスキップしてください。 ウィザードはアカウント作成の一環として 1 つをミントします。 --email、--full-name、--accept-tos、および --region はすべて、create-account を --agent と組み合わせる際に必要です。これは、ウィザードにこれらを要求する 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アカウント、完全自動。**AmplitudeプロジェクトのAPIキーをインラインで渡すことで、ウィザードがOAuthをスキップできるようになります。 --app-id <id>を追加して、実行を特定のAmplitudeアプリに紐付けます。 エージェントに必要なスコープフラグはこれだけです。ウィザードは組織、プロジェクト、および環境を自動的に導出するからです：

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

既存のAmplitudeアカウント、同じマシンでの事前ログイン。 npx @amplitude/wizard loginを1回指定すれば、その後は--api-keyを省略でき、ウィザードは保存済みのOAuthトークンを再利用します。

重要なフラグ

npx @amplitude/wizard manifestを実行すると、機械可読なCLIの全機能（フラグ、環境変数、終了コード、用語集）がJSON形式で出力されます。

計画、適用、検証

人間が diff のループに参加することを望むエージェントの場合、実行を 3 つのフェーズに分割します。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 以外の終了コードで終了します。

その他、エージェント対応のサブコマンドとしては、detect --json、status --json、auth status --json、auth tokenなどがあり、これらは他のスクリプトから保存されたOAuthトークンを読み取るために使用されます。

MCPサーバーモード

npx @amplitude/wizard mcp serveは、ウィザードの読み取り専用操作を、標準入出力経由の Model Context Protocol ツールとして公開します。 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を公開します。applyをplan_setup 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については依然としてユーザーによる明示的な入力が必要であるため、プロンプトが一切表示されないわけではありませんが、ブラウザベースのOAuthハンドシェイクは省略されます。

データが流れた後に試すべきこと

• 最初のセッションリプレイを視聴する：ユーザーがアプリでどのような体験をしているかを正確に確認できます。
• Webテストを開始：ビジュアルエディターを使用すれば、追加のコードを一切書かずに機能のA/Bテストを実施できます。
• ガイドまたはアンケートを作成する：製品内でのフィードバックや特定のユーザーセグメントへのメッセージを収集します。

フィードバック

このウィザードはオープンソースです。GitHubから、ソースの表示、問題のレポート、開発への貢献ができます。

ご意見やご要望をぜひお寄せください：wizard@amplitude.com。