nx-cloud-api

Files (2)

• SKILL.md
• extraction-and-calculation.md · references/

SKILL.md (first lines)

# 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:

| Credential            | Headers                                                           |
| --------------------- | ----------------------------------------------------------------- |
| Workspace (CI) token  | `Authorization: Bearer <token>`                                   |
| OAuth access token    | `Nx-Cloud-OAuth-Access-Token: <token>` and `Nx-Cloud-Id: <id>`    |
| Personal access token | `Nx-Cloud-Personal-Access-Token: <token>` and `Nx-Cloud-Id: <id>` |

## 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

```sh
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`:

From nrwl/nx-ai-agents-config, MIT.

More from nrwl/nx-ai-agents-config