Reference
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.
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 | ❌ | composer-2.5 | Model id. A bare id runs with the account's default settings and [param=value,...] overrides them, e.g. grok-4.7 or grok-4.7[fast=true]. |
working-directory | ❌ | . | Working directory for the agent to operate in |
permissions | ❌ | read-only | Built-in tools the agent may use: read-only (read, search, and web tools), read-write (adds file edits; no shell or subagents), or full (the SDK's default toolset). |
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 |
Notes on inputs
permissions
Mapped to the SDK's tool allow and deny lists: read-only offers the read, search, and web tools only; read-write removes shell and task from the default toolset; full leaves the SDK default. It restricts the main agent loop and is not a sandbox. The full table is on Behaviour.
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. The input is kept so existing workflows keep validating.
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 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.
Last updated on