skill skill

safe

This skill captures terminal screenshots by running commands via ttyd and headless Chrome, enabling documentation and testing with PNG sequences.

npx playbooks add skill yarlson/scr --skill skill

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.3 KB

---
name: scr
description: Automated terminal screenshots. Run CLI/TUI commands, script interactions, capture PNGs. Use when generating documentation, testing terminal apps, or capturing command output sequences.
license: MIT
---

Capture terminal screenshots by running commands through ttyd + headless Chrome, executing scripted keypresses, saving PNG sequences.

## Syntax

```
scr [flags] <command> [script]
```

## Flags

| Flag | Default         | Purpose             |
| ---- | --------------- | ------------------- |
| `-o` | `./screenshots` | Output directory    |
| `-i` | `500ms`         | Screenshot interval |
| `-t` | `60s`           | Timeout             |
| `-p` | `7681`          | ttyd port           |
| `-v` | `false`         | Verbose             |

## Script Actions

| Action     | Syntax             | Behavior                                                           |
| ---------- | ------------------ | ------------------------------------------------------------------ |
| Type       | `Type 'text'`      | Type text (50ms/char default); supports spaces + ASCII punctuation |
| Type speed | `Type@30ms 'text'` | Type with custom per-char delay                                    |
| Sleep      | `Sleep 500ms`      | Pause for duration (ms or s)                                       |
| Key        | `Enter`            | Press key once                                                     |
| Key repeat | `Down 3`           | Press key N times                                                  |
| Key delay  | `Enter@200ms`      | Delay before keypress                                              |
| Ctrl combo | `Ctrl+C`           | Send control character                                             |

## Supported Keys

`Enter` `Tab` `Escape` `Space` `Backspace` `Delete` `Up` `Down` `Left` `Right` `Home` `End` `PageUp` `PageDown`

---

## Common Patterns

### Static capture (no interaction)

```bash
scr "ls -la"
scr "git status"
scr "cat README.md"
```

### Type and execute

```bash
scr bash "Type 'echo hello' Enter"
scr bash "Type \"echo 'hello / ?'\" Enter"
scr bash "Type 'npm test' Enter Sleep 5s"
```

### Menu navigation (fzf, gum, etc.)

```bash
scr "seq 1 20 | fzf" "Down 5 Enter"
scr "gum choose A B C" "Down Down Enter"
```

### Editors

```bash
scr vim "Type 'i' Type 'Hello' Escape Type ':wq' Enter"
scr nano "Type 'Hello' Ctrl+X Type 'y' Enter"
```

### REPLs

```bash
scr python3 "Type 'print(1+1)' Enter Sleep 500ms Ctrl+D"
scr node "Type '2+2' Enter Sleep 300ms Type '.exit' Enter"
```

### Long-running processes

```bash
scr htop "Sleep 3s Ctrl+C"
scr -t 120s "npm run build" "Sleep 60s"
```

### Custom output

```bash
scr -o ./docs/images "git log --oneline"
scr -i 200ms bash "Type 'ls' Enter"
```

---

## Error Handling

Parse errors include position:

```
Error: parse script: position 23: expected quoted string after Type
```

Unknown key:

```
Error: unknown key 'Foo' at position 15; valid keys: Enter, Tab, ...
```

## Prerequisites

Requires `ttyd` in PATH. If installed via Homebrew, `ttyd` is installed automatically as a dependency; otherwise install `ttyd` separately.

Chrome/Chromium must be available (chromedp auto-detects).

## Output

Screenshots saved as `screenshot_001.png`, `screenshot_002.png`, etc.

Capture sequence:

1. Initial terminal state
2. Periodic snapshots (per `--interval`)
3. Final state after script completes

Overview

This skill automates terminal screenshots by running CLI/TUI commands in a headless terminal and capturing PNG sequences. It drives ttyd plus headless Chrome to execute scripted keypresses, timed sleeps, and typed input. Use it to generate reproducible visual documentation, test terminal UIs, or record command-output sequences.

How this skill works

It launches a terminal session exposed via ttyd, opens that session in headless Chrome, and takes PNG snapshots at a regular interval plus at start and end. You can provide a short script of actions (Type, Sleep, Key, Ctrl combinations) to simulate user interaction. Screenshots are saved in a numbered sequence so you can embed them in docs or review UI changes over time.

When to use it

Creating step-by-step visual documentation for CLI tools or tutorials
Testing and visually verifying TUI behavior across changes
Capturing demo sequences of interactive programs like fzf, vim, or REPLs
Recording build, test, or runtime output sequences for QA or audit
Generating assets for marketing or release notes showing command outputs

Best practices

Write concise scripts that mirror the user flow you want to show; prefer explicit Sleeps when waiting for output
Use Type@<ms> to adjust typing speed for reproducible timing in fast UIs
Increase timeout (-t) for long-running commands and use Sleep to capture intermediate states
Choose a shorter interval (-i) for smoother sequences and a longer interval for static commands to reduce file count
Validate that ttyd and Chrome/Chromium are installed and accessible before running

Example use cases

Capture a quick command output: scr "ls -la" to produce a single screenshot
Document an interactive flow: scr bash "Type 'echo hello' Enter" to show typed commands and results
Record menu navigation: scr "seq 1 20 | fzf" "Down 5 Enter" to capture selection steps
Save editor sessions: scr vim "Type 'i' Type 'Hello' Escape Type ':wq' Enter" to document in-editor changes
Test TUI behavior under CI: run scr inside automation to produce PNGs for visual regression

FAQ

What dependencies are required?

ttyd must be on PATH and Chrome/Chromium must be available for headless capture.

How are screenshots named and ordered?

Files are saved as screenshot_001.png, screenshot_002.png, etc., reflecting initial, periodic, and final snapshots.