You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(readme): enhance usage instructions and clarify action setup
Updated the README to improve clarity on using the Cursor GitHub Action. Added a Quickstart section, revised input and output descriptions, and emphasized the use of the main branch for action usage. Adjusted examples for better readability and consistency.
| `summary` | Agent text output (used for step-to-step handoff). |
46
+
| `exit-code` | Exit code returned by `cursor-agent`. |
47
+
| `cache-hit` | `"true"` when CLI install came from cache. |
47
48
48
49
## Examples
49
50
50
-
### PR code review
51
+
### PR review comment
51
52
52
53
```yaml
53
54
name: Cursor Code Review
@@ -59,18 +60,18 @@ jobs:
59
60
review:
60
61
runs-on: ubuntu-latest
61
62
steps:
62
-
- uses: actions/checkout@v4
63
+
- uses: actions/checkout@v6
63
64
64
65
- name: Run Cursor Agent
65
-
uses: PunGrumpy/cursor-action@v1
66
66
id: review
67
+
uses: PunGrumpy/cursor-action@main
67
68
with:
68
69
api-key: ${{ secrets.CURSOR_API_KEY }}
70
+
permissions: read-only
69
71
prompt: |
70
72
Review the staged changes in this repository.
71
-
Focus on: correctness, security, and performance.
73
+
Focus on correctness, security, and performance.
72
74
Be concise.
73
-
permissions: read-only
74
75
75
76
- name: Comment on PR
76
77
uses: actions/github-script@v7
@@ -84,68 +85,71 @@ jobs:
84
85
})
85
86
```
86
87
87
-
### Pin a specific CLI version
88
+
### Pin a specific Cursor CLI build
88
89
89
90
```yaml
90
-
- uses: PunGrumpy/cursor-action@v1
91
+
- uses: PunGrumpy/cursor-action@main
91
92
with:
92
93
api-key: ${{ secrets.CURSOR_API_KEY }}
93
94
prompt: "Generate a changelog entry for the latest commit."
94
95
cursor-version: "2026.03.20-44cb435"
95
96
```
96
97
97
-
### Read-write permissions (agent can modify files)
98
+
### Allow file edits
98
99
99
100
```yaml
100
-
- uses: PunGrumpy/cursor-action@v1
101
+
- uses: PunGrumpy/cursor-action@main
101
102
with:
102
103
api-key: ${{ secrets.CURSOR_API_KEY }}
103
-
prompt: "Fix any TypeScript type errors in src/"
104
+
prompt: "Fix TypeScript type errors in src/."
104
105
permissions: read-write
105
106
working-directory: ./src
106
107
```
107
108
108
-
---
109
-
110
-
## Version Resolution
109
+
## How this action behaves
111
110
112
-
`cursor-version: latest` resolves to the current published Cursor lab build before download. The action first checks Cursor's lab `latest-version` endpoint and, if that endpoint is unavailable or returns an access error, falls back to parsing the official [`https://cursor.com/install`](https://cursor.com/install) installer script.
111
+
### Version resolution
113
112
114
-
If you want reproducible installs, pin `cursor-version` to an exact lab build id such as `2026.03.20-44cb435`. Values like `1.2.3` are not published Cursor lab artifact versions and will fail to download.
113
+
- `cursor-version: latest` resolves to a concrete Cursor lab build before download.
2. Fallback to parsing `https://cursor.com/install`
117
+
- For reproducible installs, pin an exact lab build id.
115
118
116
-
---
119
+
### Invocation strategy
117
120
118
-
## Caching
121
+
- Primary invocation: `cursor-agent chat ...`
122
+
- If chat fails with a likely CLI mismatch (for example `unknown command`) or empty output, the action retries with headless print mode (`-p --output-format text`).
123
+
- A preflight print probe is also run to improve auth/entitlement diagnostics in job summary output.
119
124
120
-
The action caches the extracted Cursor CLI package across jobs using `@actions/cache`. The cache key includes the platform, architecture, and resolved version, so:
125
+
### Caching
121
126
122
-
- `latest`resolves to a concrete version before caching — it won't re-download on every run once cached.
123
-
- Pinning a version (e.g. `2026.03.20-44cb435`) gives you a stable, reproducible cache hit every time.
124
-
- The full installed package is cached, not just the `cursor-agent` launcher.
127
+
- The extracted CLI package is cached by platform, architecture, and resolved version.
128
+
- Using `latest` still hits cache after it resolves to a concrete build.
129
+
- Pinning a build id gives stable cache keys across runs.
125
130
126
-
---
131
+
## Local development
127
132
128
-
## Troubleshooting (CI / smoke tests)
133
+
### Prerequisites
129
134
130
-
### `cursor-agent` exits with code 1 and little or no output
135
+
- Node.js 24 (matches CI and release workflows)
136
+
- Bun
131
137
132
-
- **API key & billing**: Ensure `CURSOR_API_KEY` is set and valid. Agent / headless features may require an eligible Cursor plan; some errors only show up once the CLI talks to Cursor’s API.
133
-
- **Model**: The default `model: auto` should work for most accounts. If you pin `model`, confirm that model is available for your subscription.
134
-
- **CI model override**: In this repo's CI workflow, `smoke-test.env.CURSOR_SMOKE_TEST_MODEL` controls the model used by the smoke test. Set it to a known-good model for your account if `auto` fails.
135
-
- **CLI contract changes**: This action first runs `cursor-agent chat …` (with `--allow-*` flags from `permissions`). If that fails with no output or an “unknown command”-style error, it automatically retries using headless **print mode** (`-p`, `--output-format text`) as documented in the [Cursor headless CLI](https://cursor.com/docs/cli/headless) docs.
136
-
- **Debugging**: On failure, check the **job summary** — it includes `cursor-agent --version`, which invocation mode was used (`chat` vs `print`), an auth/entitlement preflight result, merged stderr, and a **Diagnostics** section when both attempts fail.
137
-
138
-
### Reproduce locally
138
+
### Validate changes locally
139
139
140
140
```bash
141
-
export CURSOR_API_KEY='your-key'
142
-
cursor-agent --version
143
-
cursor-agent -p --no-interactive --output-format text --model auto "Say 'smoke test passed' and nothing else."
141
+
bun install
142
+
bun run typecheck
143
+
bun run test
144
+
bun run build
144
145
```
145
146
146
-
To run the action entrypoint locally from this repo:
147
+
If you changed source files, commit updated `dist/` as well (`CI` fails when `dist/` is out of date).
- `CI`workflow runs `typecheck`, `test`, and `build` on pushes and pull requests.
170
+
- On pushes to `main`, CI also runs a smoke test job using this action (`uses: ./`).
171
+
- `Release`workflow runs on pushes to `main`, executes tests/build, then uses Changesets to open/update a release PR or publish.
172
+
- After the first stable release, major tags (`v1`, `v2`, ...) are managed by the release flow so `@v1` tracks the latest `v1.x.x`.
173
+
174
+
## Troubleshooting
166
175
167
-
This project uses [changesets](https://github.com/changesets/changesets) for versioning. See [`.changeset/README.md`](.changeset/README.md) for how to add a changeset when contributing.
176
+
### `cursor-agent` exits non-zero
168
177
169
-
Major version tags (`v1`, `v2`, …) are kept up-to-date automatically by the release workflow, so `uses: PunGrumpy/cursor-action@v1` always resolves to the latest `v1.x.x` release.
178
+
- Confirm `CURSOR_API_KEY` is present and valid.
179
+
- If you set `model`, verify your account can access it (try `auto` first).
180
+
- Check the job summary for:
181
+
- `cursor-agent --version`
182
+
- invocation mode used (`chat` or fallback `print`)
183
+
- preflight/auth diagnostics and merged stderr
184
+
185
+
### Smoke test model issues in this repo
186
+
187
+
This repository's smoke test uses `CURSOR_SMOKE_TEST_MODEL` (default: `auto`) in `.github/workflows/ci.yml`. If smoke tests fail due to model access, set it to a known-good model for your account.
188
+
189
+
## Versioning
170
190
171
-
---
191
+
This project uses [Changesets](https://github.com/changesets/changesets). See [`.changeset/README.md`](.changeset/README.md) for contribution workflow details.
0 commit comments