nx-cloud-api

Imported from nrwl/nx-ai-agents-config (skills/nx-cloud-api/SKILL.md). Install upstream with npx skills add nrwl/nx-ai-agents-config --skill nx-cloud-api. Copyright stays with the author.

Nx Cloud API

Answer a defined workspace-data question with npx nx-cloud api, the read-only Nx Cloud Public API command. This is an API access skill, not a report generator or configuration editor. Run every command from the workspace root so the command finds nx.json, or pass --nxCloudId <id> to name the workspace (see Authentication).

Run npx nx-cloud api --help (or npx nx-cloud api alone) once for syntax and options. This skill covers the workflow around it.

All output is JSON. stdout carries only the response data. stderr carries one JSON object per line: {"error": ...}, {"output": ...}, and, with -i or NX_VERBOSE_LOGGING, {"response": ...} and {"log": ...}. The one exception is an asset download, whose raw bytes go to the -o file.

Non-negotiable rules

• Discover endpoints from the live spec. Use npx nx-cloud api --list-operations to find a route and npx nx-cloud api --describe <operationId | path | link> for its parameters, response fields, and error statuses. Both show what an operation returns: list (the wrapped list below), object (the response body), or file (an asset download). Do not use remembered routes, fields, filter names, or enum values.
• Start at cipes and follow returned links values. Do not build child URLs by hand or use an internal workflow ID as a route parameter. When you must address an entity by ID, use the {placeholder} path from --describe and fill it with -p name=value. Never paste an ID into a path: IDs are raw and can contain / or : (task IDs like @scope/app:build).
• Start with one filtered page. Ask for a workspace, scope, or time range when they are missing. Do not collect history by default.
• Read the operation description from --describe. It states server limits that the command does not enforce.
• Do not use this skill to poll or monitor live CI.

Authentication

npx nx-cloud api authenticates for you; do not read credentials out of nxcloud.ini or call the API with curl. It sends the first available of:

1. A workspace token in NX_CLOUD_ACCESS_TOKEN (or NX_CLOUD_AUTH_TOKEN). When one is set, the command uses it alone and ignores any stored login.
2. The user's OAuth login from npx nx login, refreshed as needed.
3. A personal access token stored in nxcloud.ini by an older login.

A login or personal access token also needs the workspace's Nx Cloud ID, sent as Nx-Cloud-Id. The command reads it from nxCloudId in nx.json; --nxCloudId <id> overrides it and works outside an Nx workspace, so you can query a workspace you are a member of without its checkout. A workspace token always reads its own workspace and ignores the ID.

If you must call the API without the command, the headers differ per credential, and an OAuth access token is not a bearer token:

Cache boundary

The API returns recorded task and run fields. It does not query the local Nx target. cacheEnabled describes the recorded run. cacheable describes the recorded task. Neither value identifies targetDefaults, an inferred target, or Vite, ESLint, or another tool-native cache.

Do not infer cache: false from an absent project property. For cache causes, target settings, inputs, outputs, or a configuration change, use nx-cloud-cache-investigator. API data alone cannot justify a cache or inputs pull request.

Quick workflow

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"

Pass a links.* value exactly as returned; it may already carry query parameters, and -f adds more. Full URLs are accepted only on the configured Nx Cloud host. That includes app links such as https://cloud.nx.app/cipes/<id>, which resolve like the bare path cipes/<id>.

Keep API output compact

To preserve context, write every live data response to a file with -o (files are created owner-only) in a scratch directory outside the workspace. Give the file an extension. A name without one gets .json, .ndjson, or the download's own (such as .tar.gz), and the command reports the final path on stderr as {"output": {"file": "..."}}. Create the scratch directory with mktemp -d, and read a question-specific jq projection. Do not let a raw collection print into the conversation unless the user asks for it. Choose projected fields from --describe. For one row, select it first, then project only the needed fields. Delete saved data when the task is done unless the user asks to keep it.

--describe output is usually small. Pipe it through jq only when you need part of a large operation.

Exit codes and errors

Always check the exit code. Every failure prints one record on stderr, and the command adds no recovery hints; do not hide stderr with 2>/dev/null:

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

type is usage, http, network, response (an answer the command cannot use), or output (an unwritable -o file). For http, body is the server's error body, parsed when it is JSON and absent when it is empty. Exit 4 and 5 bodies carry a stable code (except 401 and an empty-body 429); branch on .error.body.code, not on the prose message.

--list-operations, --describe, and --print-api-spec do not need credentials, so they succeed even when data requests fail with 401.

Do not alter workspace configuration or credentials without the user's explicit request.

Same-session retry

For a 409 not_terminal on a known request, arrange at most one same-session wake after the entity is expected to finish. Preserve the link and filters. Stop at a terminal response.

Pagination

Every list response is wrapped, even a single page: {source, pagesFetched, fetchedItemCount, pageLimitReached, nextCursor, items}. source records the origin, endpoint, and original query. Read rows with jq '.items[]'. Non-list responses are returned as-is.

The list is complete only when the exit code is 0 and nextCursor is null. pageLimitReached: true means --pages stopped the run while more results exist. To continue, rerun the same path and filters with --cursor <nextCursor>, or state that the data is incomplete. The output's source.query records the cursor it started from.

The command fetches one page by default. Raise --pages deliberately and keep it small; prefer narrower filters over more pages. Do not fetch many flaky-tasks or task-stats pages without a narrow filter. Leave the page size alone unless needed: every page costs one unit of the organization's rate limit, and --page-size (which sets limit, max 500) only helps when raised.

If a later page fails, the command still prints what it fetched, with nextCursor at the failed page, and exits 4 or 5. Handle the error, then resume from that cursor.

--format ndjson prints only the rows, one per line, with no metadata. Nothing in its output says whether more pages exist, and it records no resume cursor. It prints each page as it is retrieved which can matter for responsiveness or very large responses. Use it only when completeness does not matter; otherwise use the default JSON output.

For multi-range extraction, task or log assets, or a calculation, read references/extraction-and-calculation.md first.

Interpret responses

Collection responses have top-level items and nextCursor. Single resources are returned as-is. Do not infer a field meaning from its name; check --describe and a live record first.

Label cache statements by evidence source:

• API response field: a recorded cacheEnabled, cacheable, cache-status, or hash value.
• Nx target query: a value from nx show project ... --json in a matching checkout.
• Tool-native cache: Unknown until its executor options are inspected.

Empty task assets

A valid task asset can have zero-byte terminal output and no output files; nx:noop commonly does. Check the matching workspace task before reporting a log-capture or archive defect.

Report

State the operations queried, filters, item counts, and whether the data is complete. State whether a result is recorded API data, a local target query, or a hypothesis. Never claim that an API-only read proved configuration provenance or tool-native cache state.