nx-cloud-api

Nx Cloud API

読み取り専用の Nx Cloud Public API コマンドである npx nx-cloud api を使って、ワークスペースデータに関する明確な質問に回答します。これは API アクセス用のスキルであり、レポート生成ツールや設定エディターではありません。コマンドが nx.json を見つけられるよう、すべてのコマンドをワークスペースのルートから実行してください。

構文とオプションを確認するため、npx nx-cloud api --help（または npx nx-cloud api のみ）を一度実行してください。このスキルでは、その周辺のワークフローを扱います。

すべての出力は JSON です。stdout にはレスポンスデータのみが出力されます。stderr には、1 行につき 1 つの JSON オブジェクトが出力されます。形式は {"error": ...}、{"output": ...}、および -i または NX_VERBOSE_LOGGING を指定した場合の {"response": ...} と {"log": ...} です。例外はアセットのダウンロードで、生バイトデータが -o ファイルに出力されます。

必ず守るルール

• エンドポイントはライブ仕様から確認してください。ルートを見つけるには npx nx-cloud api --list-operations を使い、パラメーター、レスポンスフィールド、エラーステータスを確認するには npx nx-cloud api --describe <operationId | path | link> を使います。どちらのコマンドも、操作が返すものを list（以下で説明するラップされたリスト）、object（レスポンス本文）、file（アセットのダウンロード）のいずれかで示します。記憶に頼ってルート、フィールド、フィルター名、列挙値を使わないでください。
• cipes から始め、返された links の値をたどってください。子 URL を手作業で組み立てたり、内部ワークフロー ID をルートパラメーターとして使ったりしないでください。ID でエンティティを指定する必要がある場合は、--describe に示された {placeholder} 形式のパスを使い、-p name=value で値を設定してください。ID をパスに直接貼り付けないでください。ID は生の値であり、/ や : を含むことがあります（@scope/app:build のようなタスク ID）。
• まず、フィルターを適用したページを 1 つ取得してください。ワークスペース、スコープ、または期間が指定されていない場合は、ユーザーに確認してください。デフォルトでは履歴を収集しないでください。
• --describe から操作の説明を確認してください。そこには、コマンドが強制しないサーバー側の制限が記載されています。
• このスキルを、実行中の CI のポーリングや監視に使わないでください。

キャッシュの境界

API は、記録されたタスクと実行のフィールドを返します。ローカルの Nx ターゲットには問い合わせません。cacheEnabled は記録された実行について説明し、cacheable は記録されたタスクについて説明します。どちらの値も、targetDefaults、推測されたターゲット、Vite、ESLint、その他のツール固有のキャッシュを示すものではありません。

プロジェクトプロパティがないことから cache: false と推測しないでください。キャッシュの原因、ターゲット設定、入力、出力、または設定変更については、nx-cloud-cache-investigator を使ってください。API データだけでは、キャッシュや入力に関するプルリクエストの根拠になりません。

クイックワークフロー

npx nx-cloud api --describe cipes

# Save one bounded page to a scratch file, then project only what you need.
dir="$(mktemp -d)"
npx nx-cloud api cipes \
  -f createdAfter=2026-08-01T00:00:00Z \
  -f statuses=FAILED -f statuses=CANCELED \
  -o "$dir/cipes.json"
echo "exit $?"
jq '{pageLimitReached, nextCursor, items: [.items[] | {id, status, createdAt, links}]}' "$dir/cipes.json"

# Follow a link from a previous response as-is.
npx nx-cloud api "<link from a previous response>" -o "$dir/next.json"

# Address an entity by ID only through a path parameter.
npx nx-cloud api 'runs/{runId}/tasks' -p runId="$run_id" -o "$dir/tasks.json"

links.* の値は、返されたままの形で渡してください。すでにクエリパラメーターが含まれている場合があり、-f を指定するとさらに追加されます。完全な URL を使えるのは、設定済みの Nx Cloud ホストに限られます。https://cloud.nx.app/cipes/<id> のようなアプリリンクも含まれ、裸のパス cipes/<id> と同様に解決されます。

API 出力をコンパクトに保つ

コンテキストを保つため、ライブデータのすべてのレスポンスは -o を使って、ワークスペース外のスクラッチディレクトリにファイルとして保存してください（ファイルのアクセス権は所有者のみです）。ファイル名には拡張子を付けてください。拡張子がない場合は .json、.ndjson、またはダウンロードデータ固有の拡張子（.tar.gz など）が付与され、コマンドは stderr に {"output": {"file": "..."}} の形式で最終パスを出力します。スクラッチディレクトリは mktemp -d で作成し、質問に必要な項目だけを jq で抽出してください。ユーザーから求められない限り、生のコレクションを会話に出力しないでください。抽出するフィールドは --describe から選んでください。1 行だけ必要な場合は、まずその行を選択してから、必要なフィールドのみを抽出してください。ユーザーから保存を求められない限り、作業が終わったら保存したデータを削除してください。

--describe の出力は通常小さくなっています。大規模な操作の一部だけが必要な場合に限り、jq に渡してください。

終了コードとエラー

終了コードは必ず確認してください。失敗するたびに stderr に 1 件のレコードが出力され、コマンドは復旧のヒントを追加しません。2>/dev/null で stderr を隠さないでください。

{"error":{"type":"http","message":"HTTP 409 Conflict","status":409,"url":"...","body":{"code":"not_terminal","message":"..."}}}

type は usage、http、network、response（コマンドで使用できない応答）、または output（書き込み不可の -o ファイル）です。http の場合、body はサーバーのエラー本文で、JSON の場合は解析され、空の場合は存在しません。終了コード 4 および 5 の本文には、安定した code が含まれます（401 と本文が空の 429 は除く）。文章形式の message ではなく、.error.body.code に基づいて分岐してください。

終了コード	HTTP	code	次のアクション
1	—	—	使用方法、ネットワーク、レスポンス、または出力のエラーです。stderr にある .error.type と .error.message を確認してください。フラグ、パス、または -p の値を修正するか、ホスト（NX_CLOUD_API または nxCloudUrl）、プロキシ、VPN を確認してください。
4	400	invalid_parameter	npx nx-cloud api --describe <same path> を実行し、指定されたパラメーターを修正してください。不明なクエリパラメーターは常に拒否されます。
4	400	invalid_limit, invalid_timestamp, invalid_date_range, invalid_filter	message で指定された値またはフィルターの組み合わせを修正してください。形式と上限については --describe を使用してください。
4	400	invalid_cursor	カーソルは、それを発行したリストに対してのみ有効です。同じパスとフィルターで再開するか、cursor を指定せずに最初からやり直してください。
4	401	none（body はプレーンテキスト）	ワークスペースのルートから npx nx-cloud login --status を実行してください。このコマンドには、nx.json に nxCloudId が設定された状態で npx nx-cloud login から取得した個人用アクセストークン、または NX_CLOUD_ACCESS_TOKEN に設定されたワークスペーストークンが必要です。保存済みの個人用アクセストークンは優先されるため、有効なワークスペーストークンが設定されていても、古いトークンがあると失敗します。ステータス確認で使用可能なログインがないと報告された場合に限り、npx nx-cloud login を実行してください。
4	403	plan_not_allowed	組織のプランには Nx Cloud Public API が含まれていません。ユーザーに伝えてください。再試行したり、他の人のトークンを使用したりしないでください。
4	404	not_found	パス内、または親 ID フィルター（cipeId、runGroup、stepId、agentName）内の ID が間違っています。不明な親 ID が空の結果として返されることはありません。ID を再確認するか、リンクをたどってください。
4	404	none（body なし）	パスに一致するルートがありません。通常は、@scope/app:build などの / を含む生の ID をパスに貼り付けたことが原因です。-p と {placeholder} 形式のパスを使用するか、links をたどり、--describe でパスを確認してください。
4	409	not_terminal	エンティティはまだ実行中です。これは失敗ではありません。データはまだ確定していません。以下の同一セッションでの再試行を参照してください。
4	429	rate_limit_exceeded または body なし	組織全体のクォータを使い切りました。このコマンドは Retry-After に従ってすでに 3 回再試行しています。時間をおいてから再試行し、フィルターを絞り、リクエスト数を減らしてください。
5	503	data_api_at_capacity, query_deadline_exceeded, audit_log_unavailable, rate_limit_unavailable	データは返されませんでした。このコマンドはすでに 3 回再試行しています。もう一度試す前に時間をおいてください。query_deadline_exceeded の場合は、時間範囲またはフィルターを絞ってください。
5	5xx	その他	少し待ってから 1 回再試行してください。サポートに問い合わせる際は、エンドポイント、フィルター、時間範囲、および本文にある traceId を控えてください。
--list-operations、--describe、--print-api-spec は認証情報を必要としないため、データリクエストが 401 で失敗しても正常に実行されます。

ユーザーから明示的な依頼がない限り、ワークスペースの設定や認証情報を変更しないでください。

同一セッションでの再試行

既知のリクエストで 409 not_terminal が返された場合、エンティティの処理完了が見込まれる時点で、同一セッションでの再試行を最大 1 回行うようにしてください。リンクとフィルターは維持してください。終端レスポンスが返されたら停止してください。

ページネーション

単一ページの場合も含め、すべてのリストレスポンスは次の形式でラップされます。 {source, pagesFetched, fetchedItemCount, pageLimitReached, nextCursor, items}。 source には、取得元、エンドポイント、元のクエリが記録されます。行の読み取りには jq '.items[]' を使用してください。リスト以外のレスポンスはそのまま返されます。

終了コードが 0 で、nextCursor が null の場合にのみ、リストは完全です。 pageLimitReached: true は、さらに結果がある状態で --pages により実行が停止したことを意味します。続行するには、同じパスとフィルターを指定して --cursor <nextCursor> で再実行するか、データが不完全であることを明記してください。出力の source.query には、開始時のカーソルが記録されます。

デフォルトでは、コマンドは 1 ページを取得します。--pages の値は意図的に引き上げ、少数にとどめてください。ページ数を増やすより、フィルターを絞り込むことを優先してください。絞り込みなしに flaky-tasks や task-stats のページを多数取得しないでください。必要がない限りページサイズは変更しないでください。各ページで組織のレート制限を 1 単位消費し、--page-size（limit を設定し、上限は 500）は値を大きくした場合にのみ効果があります。

後続ページの取得に失敗した場合、コマンドは取得済みの内容を出力し、失敗したページの位置を示す nextCursor を含めたうえで、終了コード 4 または 5 を返します。エラーに対処した後、そのカーソルから再開してください。

--format ndjson はメタデータなしで、行ごとにデータのみを出力します。出力には続きのページがあるかどうかを示す情報がなく、再開用カーソルも記録されません。各ページは取得のたびに出力されます。応答性や非常に大きなレスポンスを扱う場合に、この点が重要になることがあります。完全性が重要でない場合にのみ使用してください。それ以外の場合は、デフォルトの JSON 出力を使用してください。

複数範囲の抽出、タスクまたはログのアセット、あるいは計算については、まず references/extraction-and-calculation.md を読んでください。

レスポンスの解釈

コレクションレスポンスにはトップレベルの items と nextCursor が含まれます。単一リソースはそのまま返されます。フィールド名だけから意味を推測せず、まず --describe と実際のレコードを確認してください。

キャッシュに関する記述には、根拠の情報源を明記してください。

• API レスポンスフィールド： 記録された cacheEnabled、cacheable、キャッシュステータス、またはハッシュ値。
• Nx ターゲットクエリ： 一致するチェックアウトで nx show project ... --json から取得した値。
• ツールネイティブキャッシュ： エグゼキューターのオプションを確認するまでは Unknown。

空のタスクアセット

有効なタスクアセットでも、終端出力が 0 バイトで出力ファイルがない場合があります。nx:noop ではよくあることです。ログの取得やアーカイブの不具合を報告する前に、該当するワークスペースのタスクを確認してください。

報告

照会した操作、フィルター、アイテム数、およびデータが完全かどうかを明記してください。結果が記録済みの API データ、ローカルのターゲットクエリ、または仮説のいずれであるかも明記してください。API のみを読み取った結果から、設定の出所やツールネイティブキャッシュの状態が証明されたと主張しないでください。