record
record watches a human perform a workflow and writes semantic FerrisGrid actions plus smart visual checkpoints. Native recording currently requires macOS 13 or newer.
ferrisgrid record --session onboarding-demoControls
| Control | Result |
|---|---|
Control+Option+Command+Escape | Stop and finalize the sequence. |
Control+Option+Command+P | Pause or resume input observation and rolling capture. |
| Ctrl+C in the launching terminal | Stop and finalize the sequence. |
The default three-second countdown gives you time to focus the target application. The stop and pause shortcuts are reserved by the recorder and are not added to the sequence.
Smart capture
FerrisGrid records clicks, double-clicks, same-screen drags, debounced scrolls, keypresses, hotkeys, and grouped printable typing. It keeps a four-frames-per-second rolling cache in memory, then persists an initial frame, pre/post frames around semantic boundaries, and a final frame. Typing does not produce a screenshot per character; Enter, navigation keys, hotkeys, clicks, completed drags, and completed scrolls create checkpoints.
Standalone pointer movement is ignored. Cross-screen drags and native Windows/Linux event recording are not currently supported. A display-topology change stops the recording rather than writing ambiguous coordinates.
Text privacy
| Mode | Behavior |
|---|---|
redacted | Default. Keep a typed-action marker and length, but omit its content. The sequence cannot execute. |
plain | Store exact typed content. Required for replaying typed actions. |
off | Mark typed actions as omitted. The sequence cannot execute. |
Redaction applies to action payloads only. Screenshots may still show passwords, messages, personal data, or other sensitive content visible on screen. Clipboard paste hotkeys are marked as external-state dependencies; clipboard contents are never copied into the sequence.
Options
| Option | Purpose |
|---|---|
--output-dir <path> | Trace root. Defaults to .ferrisgrid. |
--session <name-or-path> | Create a named recording session; existing sessions are never overwritten. |
| `--text-mode redacted | plain |
--fps <1..30> | Rolling-cache capture rate. Defaults to 4. |
--settle-ms <ms> | Delay before a post-action checkpoint. Defaults to 300. |
--countdown-ms <ms> | Delay before event observation starts. Defaults to 3000. |
| `--format jpg | png` |
| `--resolution fast | balanced |
--max-image-edge <px> | Set an exact longest-edge cap. |
--no-downsample | Keep native screenshot dimensions. |
| `--backend native | native-macos |
Output
The result points to the session, sequences/recording.md, and the reusable sequences/sequence.md. Action files use the same compact Markdown vocabulary as act; sequence metadata adds timestamps, screen fingerprints, checkpoint reasons, and frame references.
Run ferrisgrid doctor first if capture or event observation cannot start.