cursor-agents

# Cursor Agents Use this skill to control Cursor Cloud Agents through Cursor's documented REST API at `https://api.cursor.com/v1`. Do not use `$surf`, `$browser-oracle`, or `$ask cursor-browser` as the primary control path for `https://cursor.com/agents`. Those browser paths are for visual inspection or Cursor's embedded ChatGPT Browser view IDs, not for reliable Cursor Cloud Agent lifecycle control. ## Authentication Set one of these environment variables: ```bash export CURSOR_API_KEY=... ``` Fallback names are also accepted for local compatibility: ```bash export CURSOR_AGENTS_API_KEY=... export CURSOR_SERVICE_ACCOUNT_API_KEY=... ``` The API key is never printed by this skill. Requests default to HTTP Basic auth with the key as the username and an empty password, matching Cursor's examples. Use `--auth bearer` only when calling an endpoint that explicitly requires a Bearer service account token. ## Commands ```bash # Credential and models endpoint check. ./run.sh doctor --receipt /tmp/cursor-agents-doctor.json # List supported models. ./run.sh models --json --receipt /tmp/cursor-agents-models.json # Inspect an agent. ./run.sh agent <agent-id> --json # Inspect recent runs for an agent. ./run.sh runs <agent-id> --limit 20 --json # Inspect usage for an agent or one run. ./run.sh usage <agent-id> --run-id <run-id> --json # Escape hatch for documented endpoints not yet wrapped. ./run.sh raw GET /v1/models --json ``` Mutating raw requests (`POST`, `PATCH`, `PUT`, `DELETE`) require `--yes`. Agents must not create or mutate Cursor agents unless the human explicitly authorizes the side effect. ## Receipts Every command accepts `--receipt <path>`. Receipts include: - schema version - command - endpoint path - auth mode - HTTP status - response JSON when available - bounded error details on failure Receipts intentionally omit API keys and authorization headers. ## Browser UI Boundary `https://cursor.com/agents` in Chrome can be useful for visual inspection with Surf screenshots or JavaScript reads, but it is not the operational control contract. If a user gives a Chrome tab id for that page, first confirm the tab is live for inspection, then use this API skill for agent creation, polling, runs, and usage. `$ask cursor-browser` is a different integration: it controls Cursor's embedded Browser pane through a local bridge and requires a `viewId`, not a Chrome tab id. ## Verification ```bash ./sanity.sh ``` This runs deterministic local HTTP-contract tests. It does not prove live Cursor API availability. ```bash ./sanity-live.sh ``` This performs a non-mutating live `GET /v1/models` check and writes a receipt under `/tmp`. It requires `CURSOR_API_KEY`.