checkly

Checkly

CLI と MCP のどちらを使うか、まず方針を決めてください

このスキルは、シェルで npx checkly CLI を実行します。Checkly MCP サーバーが対応するのは一部の操作、つまりアカウントのライブ操作（ステータスと結果の確認、テストセッション、根本原因分析（RCA）、既存のチェックの実行、インシデント）です。Monitoring as Code の作成、テスト、デプロイができるのは CLI だけです。

Checkly API と通信する最初のコマンドを実行する前に、次の手順で方針を決めてください。

1. シェルにアクセスできない場合（チャットのみのセッション）：このスキルに従うのをやめ、Checkly MCP ツールが接続されていればそれを使用してください。接続されていない場合は、Checkly を操作するにはシェルまたは Checkly MCP サーバーが必要だとユーザーに伝えてください。
2. シェルにアクセスできる場合：npx checkly whoami を一度実行してください。
   • 成功した場合 → すべての操作に CLI を使用し、Checkly MCP ツールも接続されている場合でも、このスキルに従ってください。
   • 認証エラーで失敗するか、action_required のログイン行が出力される場合（未ログイン）：タスクに応じて対応してください。
     • チェックの作成、テスト、デプロイ：MCP では対応できません。CLI からご自身でログインするか（後述の「エージェントとしてログインする」を参照）、ユーザーがキーの使用を希望する場合は、環境変数または .env で CHECKLY_API_KEY と CHECKLY_ACCOUNT_ID を設定するよう依頼してください。その後、whoami を再実行してください。ログインしていない状態を回避して作業を進めてはいけません。
     • アカウントのライブ操作（ステータス、結果、テストセッション、RCA、実行、インシデント）：Checkly MCP ツールが接続されていれば、そちらに切り替えてログインコードは無視してください。まず MCP の whoami ツールを呼び出し、どのアカウントを操作しているかユーザーに伝えてください。MCP も接続されていない場合は、上記の手順で CLI を認証するようユーザーに依頼してください。

切り替え後も、次の 2 つのルールは常に適用されます。

• アカウントの一致。 CLI 認証と MCP セッションで異なるアカウントが使われることがあります。ユーザーが複数のアカウントに属していることもよくあります。同じタスクで CLI と MCP の結果を混在させる前に、両方が同じアカウント ID を使用していることを必ず確認してください。また、切り替え後は必ずアカウント名を明示してください。
• 書き込み操作には引き続き確認が必要です。 CLI の確認手順（後述）は MCP には引き継がれません。書き込み操作（例：インシデントの作成）のために切り替える場合は、ツールを呼び出す前に、予定している変更を提示してユーザーの承認を得てください。

エージェントとしてログインする

npx checkly login はターミナルを必要としません。また、認証が必要なコマンドは、認証情報が保存されていない場合に自動的にログインを開始するため、手動で実行することはほとんどありません。JSON を 1 行出力して終了します。別のコマンドから開始された場合、その行は stderr に出力されます。出力された内容をそのまま伝えてください。推測してはいけません。

• {"status":"action_required","reason":"login_required","verification_uri_complete":…,"user_code":…,"expires_in":…} — 人間による承認が必要です。URL とコード（expires_in 秒間有効）をユーザーに伝えてください。Checkly アカウントを持っていないユーザーは、同じページから登録できます。ユーザーが完了したと言うのを待たずに、最初の next コマンド（npx checkly login --wait）を実行してください。承認後にこのコマンドが戻り、下記の行が出力されます。バックグラウンドで実行してください。最大で expires_in 秒間待機するため、シェルのコマンドタイムアウトより長くなることがあります。ユーザーが承認する前に停止した場合は、もう一度実行してください。同じコードが引き続き有効です。（別のコマンドからログインが開始された場合は、2 つ目の next エントリーに記載されているとおり、その後でそのコマンドを再実行してください。）承認前に --wait なしで実行すると、コードが再表示されます（古いコードの期限が近い場合は新しいコードが表示されます）。常に最新の user_code を伝えてください。ログインが完了するまでは、複数の Checkly コマンドを並行して実行しないでください。
  • 行に verification_uri はあるものの user_code がない場合は、CLI と同じマシンで URL を開く必要があります。コマンドは終了せずにその操作を待つため、URL を伝えられるようにバックグラウンドで実行してください。
  • URL がなく、next に when がない場合は、そのコマンドを今すぐバックグラウンドで実行し、出力内容を伝えてください。ユーザーが完了した後、元のコマンドを再実行してください（それより前に実行しても、この行が繰り返し表示されるだけです）。
• {"status":"action_required","reason":"select_account","choices":[…],"next":[…]} — キーは保存されていますが、ユーザーはいくつかのアカウントに属しています。まだデフォルトのアカウントがないため、アカウントを選択または指定するまで、すべてのコマンドはここで停止します。ユーザーがすでに指定していない限り、どのアカウントを使うか尋ねてください。ユーザーが示したアカウント名または ID が choices のエントリー 1 つに完全に一致する場合は、そのアカウントが選択されたものとみなします。自分で選んではいけません。尋ねられない場合でも、処理を停止して、選択可能なアカウントを伝えてください。2 回目のブラウザー操作はありません。その後、次のいずれかを実行してください。
  • npx checkly login --account-id <id> を実行して、以降のコマンドのデフォルトに設定する。
  • コマンドの前に CHECKLY_ACCOUNT_ID=<id> を付けて、そのコマンドだけを対象アカウントで実行する（下記の「複数のアカウントを使う」を参照）。
• {"status":"success","reason":…,"message":…,"accountId":…,"accountName":…,"defaultAccount":…} — 完了です。defaultAccount は保存されているデフォルトです（保存されていない場合は null）。CHECKLY_ACCOUNT_ID が設定されている間は、メッセージに記載されているとおり、コマンドは代わりにそのアカウントを使用します。現在利用しているアカウントをユーザーに伝えてください。
• {"status":"error","reason":…,"message":…} — メッセージを伝えてください。ループして再試行してはいけません。reason は access_denied、expired_token、code_used（新しいコードを取得するため、ログインを再実行してください）、account_not_found、no_accounts、invalid_response、network_error（ログインサーバーに接続できませんでした）、api_error、env_credentials（CHECKLY_API_KEY が設定されているため、API キー認証情報が使用されています。ログインするにはユーザーがこの設定を解除する必要があります）、または login_failed のいずれかです。別のユーザーとしてログインするには、まず npx checkly logout を実行してください。

ブラウザーのないホストでは、CLI がブラウザーを開こうとしないように CHECKLY_NO_BROWSER=1 を設定してください。URL とコードはどちらの場合も出力されます。フラグの形式は --account-id と --no-browser です。

複数のアカウントを使う

checkly login は特定のアカウントではなくユーザーに紐づくため、所属するすべてのアカウントで機能します。別途指定しない限り、コマンドではデフォルトのアカウントが使用されます。

• アカウントを一覧表示する： npx checkly whoami は、現在使用中のアカウント、デフォルトのアカウント、ユーザーが所属するその他のアカウントを表示します。--output json を指定すると、accountSource（login：デフォルト、account_override：CHECKLY_ACCOUNT_ID によるアカウント指定、environment：1つのアカウントに紐づく CHECKLY_API_KEY 経由の API キー認証情報）と defaultAccount も表示されます（API キー認証情報の場合、および CHECKLY_ACCOUNT_ID でアカウントを指定していてデフォルトがまだ選択されていない場合は null です。どちらも指定されていない場合、コマンドは代わりに select_account で停止します）。
• 1つのコマンドだけ別のアカウントを使う： コマンドの前に CHECKLY_ACCOUNT_ID=<id> を付けます（CHECKLY_ACCOUNT_ID=<id> npx checkly test-sessions get <id>）。保存済みのログイン情報を使い、デフォルトは変更しません。デフォルト以外のアカウントに関わるタスク（例：別のアカウントの CI テストセッション）では、ユーザーに知らせずにデフォルトを変更しないよう、この方法を優先してください。保存済みのログイン情報がない場合、コマンドはまずログインし（上記のとおりコードを伝えます）、その後そのアカウントを使用します。デフォルトは保存されません。指定した ID がユーザーのアカウントに含まれていない場合、ログイン情報が使えるアカウントの一覧とともにエラーになります。
• シェルまたは .env 内の CHECKLY_ACCOUNT_ID： CHECKLY_API_KEY が設定されていなければ、デフォルトに関係なく、解除するまでのすべてのコマンドでコマンドの前に指定した場合と同じように機能します。その場合、ログイン時にアカウントを選択する必要はありません。コマンドはそのアカウントを使用し、デフォルトは保存されません。コマンドラインでの指定は .env の値より優先されます（.env はすでに設定済みの変数を上書きしません）。whoami はその旨を表示し、login と switch は、保存しようとするデフォルトより優先されることを警告します。デフォルトを適用したい場合は、該当の変数を削除する必要があります（プロジェクトを特定のアカウントに固定するため、意図的に .env に残している場合もあります）。
• デフォルトを変更する： ユーザーから依頼された場合に限り、npx checkly switch --account-id <id> を実行します。変更は即座に適用されます（確認手順はなく、元に戻すには切り替え直すしかありません）。Account switched to … というプレーンテキストの行が表示されます。npx checkly whoami で確認してください。--account-id を指定しない場合、switch は保存済みの defaultAccount（または null）と choices を含む select_account 行を表示します。
• 見つからない場合： ID による検索で何も見つからない場合、メッセージには検索対象のアカウント名が表示されます。--output json を指定すると、エラーには hint と searchedAccount フィールドも含まれます。リソースが別のアカウントにある可能性がある場合は、該当する可能性のあるアカウントごとに CHECKLY_ACCOUNT_ID=<id> を指定してコマンドを再実行してください。

まず最新のアクション一覧を必ず読み込む

必須： Checkly に関する質問に回答する前に、npx checkly skills を実行して、最新のアクション一覧を取得してください。記憶や以前のコンテキストに頼らないでください。CLI が信頼できる情報源であり、リリース間でアクションが変更される場合があります。npx checkly skills はローカルで実行されるため、認証や API アクセスは不要です。上記の手順で設定を済ませる前でも実行できます。

続いて npx checkly skills <action> を実行し、必要なアクションの最新の詳細を読み込んでください。

npx checkly skills install を使うと、このスキルをプロジェクトにインストールできます（Claude Code、Cursor、Codex などに対応しています）。

記録されたテストセッションを調査する場合は、npx checkly skills investigate test-sessions を実行してください。

npx checkly skills による段階的な情報開示

このスキルは、コンテキストを効率的に使えるよう、次のように構成されています。

1. メタデータ（約80トークン）：フロントマターに記載された名前と説明
2. 基本の手順（約1Kトークン）：参照コマンドへのリンクを含む、メインの SKILL.md の内容
3. 参照コマンド（必要に応じて読み込み）：例を含む、詳細な構成要素のドキュメント

エージェントは各タスクに必要な情報を読み込みます。

プランの確認

チェックを設定する前に、npx checkly account plan --output json を実行して、現在のプランで利用できる機能、ロケーション、上限を確認します。無効になっている利用権に、セルフサービスでの購入ページまたはエンタープライズ向けの営業窓口への upgradeUrl が含まれている場合があります。含まれている場合に限り、ユーザーに共有してください。含まれていない場合、その利用権は利用できません。

詳細は npx checkly skills manage を実行して、リファレンス全体を確認してください。

確認プロトコル

書き込みコマンド（例：incidents create、deploy、destroy）は実行されず、代わりに confirmation_required JSON エンベロープと終了コード 3 を返します。**必ず changes をユーザーに提示し、confirmCommand を実行する前に承認を待ってください。**これは個々の書き込みコマンドすべてに適用されます。更新や解決にも確認が必要で、最初の作成だけではありません。唯一の例外は、変更がないプランでの checkly deploy です。承認する変更がないため、No changes. と表示され、デプロイが記録されます。--schedule-on-deploy --schedule-on-deploy-scope=all が渡されない限り、チェックはスケジュールされず、終了コード 0 で終了します。デプロイでチェックがスケジュールされるのは、--schedule-on-deploy が渡された場合のみです。その場合、変更されたチェックのみが対象になります。ただし、--schedule-on-deploy-scope=all を指定するとすべてのチェックが対象になります。対象となるチェックの数がスケジュールのしきい値（デフォルトでは Checkly が設定）を超える場合は、デプロイでの最小頻度（--schedule-on-deploy-min-frequency。デフォルトでは Checkly が設定）よりも高い頻度で実行されるチェックを除外します。

confirmCommand は承認済みのコマンドで、そのまま実行できます。プロジェクト独自の CLI を実行するため npx checkly で始まり、渡したフラグを再度指定します。また、deploy の場合は、表示されたプランを --plan-token で固定し、末尾に --force が付いています。ユーザーが承認したら、そのまま実行してください。自分でコマンドに --force を追加したり、npx を削除したり、ユーザーが求めていないフラグを追加したりしないでください。

詳細なプロトコルは npx checkly skills communicate を実行して確認してください。または、deploy で何が確認されるかについては npx checkly skills configure を実行してください。

出力ストリームと終了コード

stdout にはコマンドの結果のみが出力されます。結果、--output json のドキュメント（多くの失敗時には JSON エラードキュメントも出力されます）、API パススルーの本文、および上記の確認／ドライランのエンベロープが含まれます。進行状況、警告、ヒント、プロンプト、人間が読める形式のエラーは stderr に出力されるため、npx checkly <command> --output json | jq では JSON 以外は表示されません。一部の失敗では stdout が空になるため、まず終了コードを確認してください。0 は成功（チェックが劣化していても実行は失敗しません。結果を読んで該当箇所を確認してください）、1 は失敗、2 は使用方法のエラー、3 は confirmation_required、127 は不明なコマンドです。

API パススルー（すべてのエンドポイントのフォールバック）

エンドポイントに専用の CLI コマンドがない場合は、npx checkly api を使って認証済みのリクエストを直接送信します。CLI が認証ヘッダーとベース URL を自動的に処理します。

npx checkly api /v1/checks
npx checkly api /v1/dashboards -X GET --jq '.[].name'
npx checkly api /v1/checks -X POST -F name=MyCheck -F activated:=true
npx checkly api /v1/checks -X GET -F limit=5

主なフラグ：-X（メソッド）、-F（フィールド。文字列には key=value、JSON には key:=value）、-H（ヘッダー）、--jq（jq でフィルター）、--input（ファイル／stdin からの本文）、-i／--include（レスポンスのステータスとヘッダーを stdout に出力）、--verbose（リクエスト／レスポンスのヘッダーを stderr に出力）。

ネストされたペイロード

1つのフィールドに構造化された JSON を送信するには、:= を使います。

npx checkly api /v1/checks/<id> -X PATCH \
  -F retryStrategy:='{"type":"LINEAR","maxRetries":2,"baseBackoffSeconds":10}'

大きい本文や深くネストされた本文には、--input を使って JSON ファイルをパイプで渡します。

npx checkly api /v1/checks -X POST --input ./new-check.json

ページネーション

checkly api はページを自動的にたどりません。他のすべての checkly のリストコマンドと同じように、自分でページネーションを進めてください。

読み取りエンドポイントで -F を使う場合は、必ず -X GET を明示的に指定してください。メソッドを設定しない限り、-F フラグを指定すると POST が使用されるため、-X GET を省略すると、ページネーションのパラメーターを本文としてリソースを作成しようとします。

エンドポイントがどのページネーション方式を使っているかを確認する。 -i（レスポンスヘッダーを標準出力に出力）を指定して最初のリクエストを行い、返された内容を確認します。

• ページベース → レスポンスに content-range ヘッダー（例：0-1/23 は全 23 件中の項目 0～1 を意味します）があり、通常は rel="next"／rel="last" を含む link ヘッダーもあります。本文は配列そのものです。content-range の合計件数に達するまで、または rel="next" リンクがなくなるまで、-F page=N の値を増やしてページを進めます。
• カーソルベース → レスポンス本文は { entries: [...], nextId: "...", length: N } のようなエンベロープです。次の呼び出しでは -F nextId=<value>（エンドポイントによっては -F cursor=<value>）を渡します。nextId がないか null の場合、最後まで到達しています。

# Step 1: make the first call with -i and inspect the response shape
npx checkly api /v1/checks -X GET -F limit=100 -i

# If you saw a content-range header → page-based, walk with -F page=N
npx checkly api /v1/checks -X GET -F limit=100 -F page=2 -i

# If the body had a nextId field → cursor-based, walk with -F nextId=<value>
npx checkly api /v1/status-pages -X GET -F limit=50 -F nextId=<nextIdFromPrevResponse>

エラーレスポンス

2xx 以外のレスポンスでも、レスポンス本文は標準出力に書き込まれます（API のエラーメッセージを確認してください）。CLI はコード 1 で終了します。401 では認証に関するヒントが、403 では権限に関するヒントが、404 ではドキュメントの URL が、それぞれ標準エラー出力に表示されます。

エンドポイントの確認

人が読めるエンドポイント一覧はCheckly API リファレンスを参照してください。または、OpenAPI 仕様を取得すると、パス、パラメーター、レスポンス形式を検索できる機械可読な定義を確認できます。

npx checkly skills initialize

新しい Checkly CLI プロジェクトを一から初期化してセットアップする方法を学びます。

npx checkly skills configure

Checkly の構成要素と CLI を使って、監視チェックを作成および管理する方法を学びます。

npx checkly skills investigate

チェックとテストセッションのステータスにアクセスし、失敗を分析して、試行やアセットを確認し、エラーを調査します。

npx checkly skills communicate

ステータスページを通じてインシデントを開始し、顧客とのコミュニケーションを主導します。

npx checkly skills manage

アカウントプラン、利用権、機能の制限、メンバー、保留中の招待について確認します。