---
title: Reference
description: Complete input and output reference for cursor-action.
---

The tables below are generated from `action.yml` by `bun run docs:reference`, and are checked for drift in CI.

{/* reference:start */}

### Inputs

| Input | Required | Default | Description |
| --- | --- | --- | --- |
| `cursor-version` | ❌ | `latest` | (Deprecated) The SDK automatically manages the agent version. |
| `api-key` | ✅ | — | Cursor API key for authentication |
| `prompt` | ✅ | — | Prompt to pass to cursor-agent |
| `model` | ❌ | `default` | Model id for the agent (e.g. default, composer-2). The Cursor SDK does not accept auto. |
| `working-directory` | ❌ | `.` | Working directory for the agent to operate in |
| `permissions` | ❌ | `read-only` | Validated but NOT enforced: 'read-only' does not stop the agent from editing files or running shell commands. Wired to the SDK in v2. |
| `timeout` | ❌ | `300` | Timeout in seconds for the agent run |

### Outputs

| Output | Description |
| --- | --- |
| `summary` | Text summary returned by the cursor-agent |
| `exit-code` | Exit code from the cursor-agent process |
| `status` | Run status returned by the cursor-agent (finished, error, or cancelled) |
| `duration-ms` | Execution duration in milliseconds |
| `total-tokens` | Total tokens consumed by the agent run |
| `input-tokens` | Input tokens consumed by the agent run |
| `output-tokens` | Output tokens generated by the agent run |

{/* reference:end */}

## Inputs that do nothing

### `permissions`

Validated against `read-only`, `read-write` and `full`, then discarded. It is never passed to the SDK, so tool access follows whatever your API key and account allow. `read-only` is not a sandbox and does not prevent file edits or shell commands.

v2 wires it to the SDK's `disallowedTools`, renamed to `agent-permissions` to stop it colliding with the workflow-level `permissions:` key.

### `cursor-version`

Ignored since v1.0.0. The SDK resolves the agent version itself, and pinning a Cursor build is no longer possible from this action. Passing anything other than `latest` emits a warning. It is removed in v2.

## Outputs

`summary` is model output. Pass it through `env:` instead of interpolating `${{ steps.<id>.outputs.summary }}` into a `run:` script or a `github-script` body, because interpolation splices text before execution. Every example on [Examples](/examples) follows this pattern.

`exit-code` is `0` when the agent run finishes successfully. It is `1` when the run times out, cancels, or encounters an error.

`status` reports the terminal state of the agent run: `finished`, `error`, or `cancelled`.

`duration-ms` reports the run duration in milliseconds when reported by the SDK.

`total-tokens`, `input-tokens`, and `output-tokens` report token counts from the run when available.