copilotkit-cli

CopilotKit CLI

npx copilotkit@latest <command> --via skill:copilotkit-cli

このスキルから実行するすべてのコマンドに --via skill:copilotkit-cli を付けてください。これは呼び出しがこのスキルから行われたことを CopilotKit のテレメトリに伝えるだけで、コマンドでは無視されます。 CLI が Unknown option '--via' と報告する場合、npx が古いキャッシュ版を実行しています。フラグを付けずにコマンドを再実行してください。

どのコマンドでも --help を指定すると、フラグが表示されます。以下は、誰かのプロジェクトを手作業で調べ始める前に知っておく価値のあるコマンドです。

verify — デバッグの前に実行する

まず、アプリがホスト型 Intelligence を使用しているか確認します。verify はデフォルトでホスト型 Intelligence をチェックするため、オープンソースアプリでは毎回これらのチェックに失敗します。

• Intelligence を使用していない場合： ランタイムの構築時に CopilotKitIntelligence をインスタンス化する箇所がなく、.copilotkit/project.json も存在しません。ランタイムが登録するエージェント ID を指定して、オープンソース向けチェックを実行します。

  npx copilotkit@latest verify --expect-runtime oss --round-trip --agent <id> --json --via skill:copilotkit-cli
  

  ここでは --round-trip --agent <id> が必須です。指定しないとラウンドトリップが実行されず、コマンドは成功しません。

• それ以外の場合： デフォルトのチェックを実行します。

  npx copilotkit@latest verify --json --via skill:copilotkit-cli
  

verify を成功させるためだけに login や project select を実行しないでください。これらのコマンドはホスト型 Intelligence の設定を行います。オープンソースアプリの問題は解決せず、その後も verify は失敗します。ランタイムが認証情報を使用しないためです。

このコマンドを使えば、手作業での調査に代えられます。最大11項目を確認します。ホスト型プロジェクトが選択されていること、プロジェクトの API キーが存在しアプリから読み込み可能で認証に使用できること、ランタイムが応答してエージェントを宣言し実際に認証情報を使用してスレッドのルートを提供すること、フロントエンドが独自のアセットを提供すること、ランタイムがブラウザーのオリジンを受け入れること、インストール済みの CopilotKit パッケージがランタイムの報告するバージョンと一致することを確認します。また、ランタイムのバージョン、使用中のエージェントフレームワーク、文字起こしが接続されているかどうか、リアルタイムゲートウェイの接続状況、ライセンスの状態も報告します。

11項目は上限であり、常にすべて確認されるわけではありません。照合対象がない場合、つまりフロントエンドのオリジンが見つからない、またはインストール済みパッケージが見つからない場合は、最後の3項目は省略されます。固定された項目数を前提にせず、checks[] の内容を確認してください。--expect-runtime oss を指定すると、ホスト型プロジェクトと認証情報のチェックは適用されないため、実行されるチェックは少なくなります。

重要なのは、どの URL を調べたか、またその URL の取得元はどこかを明示することです。取得元は、プロジェクトの runtimeUrl、環境変数、アプリ独自の開発設定、または想定されたデフォルトのいずれかです。手作業で調べてもこれは分かりません。また、取得元によって判定が変わります。プロジェクトが指定した URL で応答がない場合は FAIL ですが、想定されたデフォルトで応答がない場合は UNKNOWN です。コマンドが把握していないポートで動作しているアプリは、接続設定の失敗ではないためです。

便利なフラグ：

• --frontend-url <実際に開くオリジン> — ブラウザー向けのチェックを追加します。オリジンがランタイムのものと異なる場合は、実際の CORS プリフライトも実行します
• --round-trip — エージェントも実行し、その回答を読み戻します。モデル呼び出しが発生するため、明示的な指定が必要です
• --expect-runtime oss — Intelligence を使用しないセルフホスト型ランタイム向けです。/info が指定されたエージェントを宣言し、Intelligence の利用権限がないことを報告し、さらに --round-trip --agent <id> が成功した場合にのみ、終了コードがゼロになります
• --agent <id> — 複数のエージェントが登録されている場合に、実行する宣言済みエージェントを指定します
• --runtime-url <url> — プロジェクトから読み取った URL ではなく、このエンドポイントを調べます
• --header '<name>: <value>' — 複数回指定できます。プロジェクトの identifyUser が CLI から渡されないセッションを読み取る場合に必要です
• --timeout <seconds> — 回答を待つ時間です。デフォルトは90秒です

checks[] を確認し、表示された順に問題を修正してください。

• チェックは連鎖しています。実行できなかった後続のチェックには、その旨と、先に修正すべき前のチェックが示されます。そのため、最初の失敗が実際の原因です。
• UNKNOWN はチェックを実行できなかったことを意味します。チェックに合格したという意味ではなく、すべてのチェックに合格しない限り、コマンドはゼロ以外の終了コードを返します。

verify の対象外

検証がパスしてから初めて、その先に進んでください。

• ツールの実行。 --round-trip は、ツールを必要としない質問をあえて送り、コンテキストは一切送りません。そのため、ラウンドトリップが成功しても、ツールが動作しているかどうかは分かりません。
• イベントの順序とストリーミング。 実行の成否は報告されますが、その内部のシーケンスまでは報告されません。実行が開始されたまま終了しない場合や、ストリーム途中で停止する場合は、Inspector で確認してください。
• 状態の同期。 スナップショットと差分の不一致は、配線の問題ではなくエージェントの動作に起因します。

プロジェクトの開始

npx copilotkit@latest init --via skill:copilotkit-cli   # `create` is an alias for it

名前とフレームワークの入力を求め、スターターを生成し、必要に応じてサインインを行い、アプリをクラウドでホストされている Intelligence プロジェクトに接続します。入力した名前で新しいディレクトリが作成されるため、このコマンドは、まだ存在しないプロジェクトを作成する場合に使います。既存のアプリがある場合は、後述の onboard start を使用してください。

既存のアプリに CopilotKit を追加するには、クイックスタートに従うか、この作業をコーディングエージェントに任せてください:

npx copilotkit@latest onboard start --via skill:copilotkit-cli

これは、現在作業中のリポジトリを対象に、チェックポイントと検証ステップを備えたエージェント主導のフローを実行するものです。スキャフォールドを生成するわけではありません。onboard start --intent <feature> は、CopilotKit が既に導入されているアプリで、特定の機能を対象にします。

サインインとプロジェクトの選択

npx copilotkit@latest login --json --via skill:copilotkit-cli   # agent-readable JSON lines, no browser launch
npx copilotkit@latest login --via skill:copilotkit-cli          # interactive: opens a browser
npx copilotkit@latest whoami --via skill:copilotkit-cli         # who is signed in, and the active organization
npx copilotkit@latest project select --via skill:copilotkit-cli # pick or create a hosted project for this directory
npx copilotkit@latest project list --json --via skill:copilotkit-cli

CLI を操作している場合は、login --json を使用してください。引数なしの login はブラウザを開こうとしますが、これは完了させることができません。

auth コマンドはありません。使用するのは login です。

project select は選択内容を .copilotkit/project.json に記録し、プロジェクトスコープのランタイムキーを .env にプロビジョニングします:

CPK_INTELLIGENCE_API_KEY=cpk_...

CPK_INTELLIGENCE_API_KEY が正式な名前であり、CLI が書き込むのはこの名前だけです。サーバー側に保管してください。これはランタイムキーであり、フロントエンド用のトークンではないため、NEXT_PUBLIC_ や VITE_ のプレフィックスは付けないでください。プラットフォームの URL は設定しないでください。これらはマネージドホストがデフォルトで使用されるため、値を指定しても、正しいデフォルトを不適切な値で置き換えることにしかなりません。

TTY がない環境（コーディングエージェントはこれに該当します）では、project list --json で選択肢を確認し、project select --project <id> または --create <name> を使って、あらかじめ選択内容を指定してください。

その他のコマンド

コマンド	内容
skills install	このスキルをプロジェクトにインストールします（skills onboard ではオンボーディングも開始します）
typegen	実行中のランタイムから、型安全なエージェント ID を生成します
import --source adk|langgraph --dry-run	過去のスレッドを Intelligence にインポートする内容をプレビューします
license create / license list	ライセンストークンを発行・一覧表示します
channels	Slack または Microsoft Teams 向けのマネージド Intelligence Channels をセットアップします
framework list	create が受け付けるエージェントフレームワークと、そのフラグを表示します
logs	CLI のログパス、または最近のログ行を表示します
telemetry	CLI のテレメトリー設定を表示または変更します
docs	ドキュメントを開きます
version	バージョン、ビルド、コミットを表示します

CLI は利用データを収集します。DO_NOT_TRACK=1 または COPILOTKIT_TELEMETRY_DISABLED=1 を設定すると、収集をオプトアウトできます。