Record your mouse. Replay your workflow.
Repeat clicks, drags, and scrolling in your macOS apps.
A native terminal app. Local recordings. No cloud service.
Install · Open the app · Usage guide · Release notes · Developer guide
Rendered from the app with an example take. Runs in your terminal, not a separate desktop window.
Repeat a product walkthrough, revisit a scrolling interaction, or reproduce a mouse-driven UI issue without performing every gesture again.
flowchart LR
record["1. Record your actions"] --> save["2. Save locally"]
save --> reset["3. Reset your workspace"]
reset --> play["4. Replay the take"]
play -.->|"Try it again"| reset
Capture movement, clicks, drags, and mouse or trackpad scrolling with their recorded timing and pauses. Replay a take, change its speed, or loop it until stopped. Recordings are local JSON files. No third-party runtime dependencies.
| Environment | Scope |
|---|---|
| System | macOS 15+ in your logged-in desktop session. Not Windows or Linux. |
| Interface | Terminal or a local integrated terminal. A CLI, not a desktop .app. |
| Target | Mouse-driven interactions in macOS apps and browser windows, not one specific editor. |
| Not included | Typing capture, video recording, UI-element recognition, or automatic app launching. |
Important
Replay sends real mouse input at recorded screen coordinates. Restore the app state and display layout yourself, and start with a disposable document. The same event stream does not guarantee identical app behavior.
Requires Swift 6+ through Apple's Command Line Tools or Xcode 16+.
If needed, install the tools with xcode-select --install.
Install the stable release through this project's Homebrew tap:
brew tap Just-Jan/cursor-replay-cli https://github.com/Just-Jan/cursor-replay-cli
brew install Just-Jan/cursor-replay-cli/cursor-replay
cursor-replay doctorHomebrew makes cursor-replay available on its normal PATH.
Prefer a local build? See installation from source.
In System Settings > Privacy & Security, grant Accessibility and
Input Monitoring to the app hosting your terminal. If macOS lists the
executable itself, enable that entry as appropriate. Restart the terminal if
needed and rerun doctor. Permission details.
From any folder, open Terminal and run:
cursor-replayUse a hyphen, not cursor replay. The interactive menu opens in that terminal;
installation does not add an Applications or Spotlight icon.
- Press R and switch to your app during the three-second countdown.
- Perform your actions, then press Esc to stop and save.
- Wait for the save confirmation, then reset your app to its starting state.
- Press P in the terminal and switch back during the countdown.
Use Up/Down arrows to browse saved recordings; the selected take is marked >. The list shows two takes at a time. Backspace/Delete asks before removing the selected take: Y deletes it permanently; N or Esc keeps it. Press P to play it once, or L to loop it until S or Esc. The countdown runs only once; the target app is not reset between repetitions.
S also stops, but needs terminal focus. Q or Ctrl+C quits, saving an active recording first. Esc is listen-only: the target app receives it too.
Menu recordings live in ~/Library/Application Support/Cursor Replay CLI/recordings.
Treat captures as private interaction data, not public fixtures.
Use record, play, info, and verify in scripts. For example,
cursor-replay play demo.json --speed 0.5 --loop 3 replays a take at half speed
three times. Command reference.