@vorec/cli

Record narrated tutorial videos via the Vorec Recorder for macOS. CLI for AI coding agents — your agent drives the recorder, you review the MP4, AI writes the narration.

macOS only. Requires the Vorec Recorder desktop app — download from vorec.ai/download.

What It Does

• Drives the Vorec Recorder to capture your screen, clicks, keystrokes, and cursor path natively via ScreenCaptureKit
• Writes an MP4 + action sidecar to your local disk — nothing uploads until you say so
• You review the recording, then run vorec analyze <mp4> to upload + generate narration
• AI writes natural voice-over from the action timeline (no video re-analysis needed — actions are pre-tracked)
• Generates voice-over audio in multiple languages and narration styles
• Returns an editor URL to preview, polish, and export
• Lets agents upload intro/outro/B-roll videos and place them on the editor timeline when you explicitly ask for extra media

Quick Start

# 1. Install the Vorec Recorder for macOS
#    https://vorec.ai/download — sign in, grant Screen Recording + Accessibility

# 2. Install cliclick (used to inject actions during recording)
brew install cliclick

# 3. Connect the CLI to your Vorec account
npx @vorec/cli@latest login

# 4. Verify the recorder is ready
npx @vorec/cli@latest check

# 5. Record a tutorial
npx @vorec/cli@latest run vorec.json
#    → Writes /path/to/recording.mp4 + sidecar locally. Review it.

# 6. Generate narration when you're happy with the take
npx @vorec/cli@latest analyze /path/to/recording.mp4

Requirements

• macOS (Apple Silicon or Intel)
• Node.js 18+
• Vorec Recorder for macOS — vorec.ai/download, signed in, with Screen Recording + Accessibility granted
• cliclick — brew install cliclick (used for action injection)
• Vorec API key — vorec login opens the browser flow, or vorec init for manual entry

Manifest Format

Create a vorec.json file describing the actions to record:

{
  "title": "How to create a project",
  "url": "http://localhost:3000/dashboard",
  "viewport": "full",
  "language": "en",
  "narrationStyle": "tutorial",
  "actions": [
    { "type": "click", "selector": "button.new-project", "description": "Open the create dialog", "context": "Clicks the New Project button. A create dialog appears with a title field." },
    { "type": "type", "selector": "#name", "text": "My Project", "description": "Enter the project name", "context": "Types the project name into the title field." },
    { "type": "click", "selector": "button[type=submit]", "description": "Save the project", "context": "Submits the form. The new project appears in the dashboard." }
  ]
}

Action types: click, type, select, hover, scroll, wait, navigate, narrate. Each action has a description (timeline label) and context (rich scene description for the narration AI).

Commands

| Command | What it does | |---------|-------------| | vorec login | Connect via browser flow (recommended) | | vorec init | Save API key manually (for non-interactive agents) | | vorec check | Verify the Vorec Recorder app + sign-in + permissions + cliclick | | vorec run <manifest> | Record via the Recorder app. Writes MP4 + sidecar locally. No upload, no credits spent. | | vorec analyze <mp4> | Upload the MP4 + sidecar, generate narration | | vorec status | Check project processing status | | vorec projects list --json | List projects accessible to the authenticated account | | vorec segments --project <id> | Read narration segments | | vorec update-narration <json> --project <id> | Push edited narration text | | vorec languages --project <id> | List available translations | | vorec translations <lang> --project <id> | Read translations for a language | | vorec update-translations <json> --language <lang> --project <id> | Push translations | | vorec media upload <path> --project <id> --wait | Upload a local MP4/WebM/MOV as a reusable project media asset | | vorec media list --project <id> | List uploaded project media assets | | vorec media inspect <assetId> --project <id> | Inspect one media asset and probe status | | vorec media delete <assetId> --project <id> | Delete an unused media asset; pass --force to remove timeline uses too | | vorec editor inspect --project <id> --json | Read a sanitized editor/timeline snapshot for agents | | vorec editor snapshot --project <id> --at <seconds> | Render one editor frame to a PNG image | | vorec editor filmstrip --project <id> --every <seconds> | Render multiple editor frames to PNG images | | vorec editor describe --project <id> | Run Vorec AI video description for planning; costs analysis credits | | vorec actions list --project <id> | List action clicks and their narration segment links | | vorec actions move --project <id> --click-index <n> --at <seconds> | Move an action marker without moving narration | | vorec actions update --project <id> --click-index <n> --x <0-1000> --y <0-1000> | Update action coordinates or labels | | vorec actions set-primary --project <id> --segment <id> --click-index <n> | Set the main action for a narration segment | | vorec actions add --project <id> --segment <id> --at <seconds> --x <0-1000> --y <0-1000> | Add a new action and optionally attach it to narration | | vorec actions delete --project <id> --click-index <n> --detach | Delete an action and remove segment references | | vorec actions verify --project <id> --click-index <n> --output frame.png | Render a snapshot at an action timestamp | | vorec narration move --project <id> --segment <id> --at <seconds> | Move narration timing without moving the action | | vorec narration move --project <id> --segment <id> --at <seconds> --with-action | Move narration and its primary action together | | vorec narration update --project <id> --segment <id> --text "..." | Update one narration script and invalidate old audio | | vorec narration attach-action --project <id> --segment <id> --click-index <n> | Attach an action to a narration segment | | vorec overlays list --project <id> | List editor overlay clips | | vorec overlays add --project <id> --type <type> --at <seconds> --duration <seconds> | Add zoom, follow-zoom, blur, spotlight, callout, text, shape, image, slide, or cursor overlay | | vorec overlays add-image <path> --project <id> --at <seconds> --duration <seconds> | Upload a local PNG/JPEG/WebP/GIF and place it as an image overlay | | vorec overlays update --project <id> --clip <id> ... | Update overlay timing or type-specific fields | | vorec overlays move --project <id> --clip <id> --at <seconds> --x <0-1000> --y <0-1000> | Move an overlay in time or position | | vorec overlays resize --project <id> --clip <id> --duration <seconds> --width <n> --height <n> | Resize overlay duration or visual bounds | | vorec overlays delete --project <id> --clip <id> | Delete an overlay clip | | vorec cursor show|hide --project <id> | Show or hide the project cursor | | vorec background get --project <id> | Read project video background settings | | vorec background set --project <id> --type gradient|color|wallpaper | Enable/update the editor background | | vorec background disable --project <id> | Turn off the editor background | | vorec export start --project <id> | Queue a production MP4 export through the existing export worker | | vorec export status <exportId> --download-url | Check export progress and optionally return a temporary download URL | | vorec export cancel <exportId> | Cancel a queued or processing export | | vorec timeline list --project <id> | List project video timeline segments | | vorec timeline split --project <id> --at <seconds> | Split an existing video segment at an exact timestamp | | vorec timeline add-video <asset-or-path> --project <id> --at <seconds> | Insert an uploaded asset or local video at a timestamp | | vorec timeline add-video <asset-or-path> --project <id> --position intro\|outro | Insert a local video or asset at the start or visual end | | vorec timeline add-video <asset-or-path> --project <id> --after-segment <segment-id> | Insert immediately after a specific video segment | | vorec timeline add-video <asset-or-path> --project <id> --before-segment <segment-id> | Insert immediately before a specific video segment | | vorec timeline remove-range --project <id> --from <seconds> --to <seconds> | Delete a time range and ripple later editor objects earlier | | vorec timeline revisions --project <id> | List restorable timeline revisions created by CLI edits | | vorec timeline undo --project <id> --revision <id> | Restore a saved timeline revision |

Run options

• --skip-narration — mark the sidecar so vorec analyze uses your manifest narration verbatim instead of letting AI rewrite it
• --profile <dir> — use a persistent Chrome profile (required for Shopify Admin / Google OAuth flows)
• --channel <channel> — chrome, chrome-beta, or msedge

Analyze options

• --language <code> — override the manifest language (en, es, fr, …)
• --narration-style <style> — override the manifest style
• --skip-narration — override the sidecar flag

Media and timeline controls

Use these only after a project exists and only when you intentionally want to add extra video to the editor timeline, such as an intro, outro, or B-roll clip.

# Upload a local video asset and wait until Vorec has probed its duration
vorec media upload ./intro.mp4 --project <id> --wait

# Add a local file directly to the timeline; the CLI uploads, waits, then inserts
vorec timeline add-video ./intro.mp4 --project <id> --position intro --muted

# Reuse an already-uploaded asset and trim it to the first four seconds
vorec timeline add-video <asset-id> --project <id> --at 42.5 --source 0:4 --muted

# To insert between two parts of an existing source segment, split first
vorec timeline split --project <id> --at 42.5 --json
vorec timeline add-video <asset-id> --project <id> --after-segment <first-segment-id-from-split> --muted

# Remove dead time or a mistake and pull later timeline objects earlier
vorec timeline remove-range --project <id> --from 18.2 --to 25.8 --dry-run
vorec timeline remove-range --project <id> --from 18.2 --to 25.8

# Undo a CLI timeline mutation
vorec timeline revisions --project <id>
vorec timeline undo --project <id> --revision <revision-id>

Timeline insertion mirrors the editor: if --at lands inside an existing video segment, Vorec snaps to the nearest segment edge, inserts the uploaded clip, then ripples later video segments, narration, source-following overlays, and action dots. --position intro resolves to timestamp 0; --position outro resolves to the current visual timeline end.

Use vorec timeline split --at <seconds> when the agent needs an exact insertion point inside a segment. Splitting preserves narration, overlays, clicks, cursor timing, media asset linkage, audio mix, and speed; it only turns one video segment into two.

Prefer segment anchors after splitting. timeline split --json returns firstSegment.id and secondSegment.id; use timeline add-video --after-segment <firstSegment.id> to place a clip exactly between the two split parts, or --before-segment <secondSegment.id> for the same boundary. This avoids manual timestamp math and makes the agent's intent inspectable.

Use vorec timeline remove-range --from <seconds> --to <seconds> for dead time, loading screens, or mistakes. It removes the visual range, trims or deletes overlapping video pieces, deletes narration/actions/clicks inside the removed window, shifts later narration/actions/clicks/overlays earlier, and prints an undo command. Run --dry-run first when an agent is proposing an edit.

Successful timeline mutations create a revision before writing. The CLI prints an undo command when a revision is available. Restoring a revision rewrites the editor timeline tables to the saved pre-edit state and creates a new revision for the restore itself, so the restore can be reversed too.

Useful flags:

• --dry-run — preview the timeline diff without inserting. For local files, dry-run is rejected because upload would still mutate project media.
• --source <start:end> — trim the asset source range in seconds.
• --speed <number> — play the inserted clip faster or slower.
• --muted / --volume <0..1> — control uploaded clip audio.
• --json — return machine-readable output for agents and scripts.

Editor inspection for agents

Use vorec editor inspect --project <id> --json before making timeline decisions. It returns project metadata, video segments, media assets, narration/action segments, clicks, tracks, overlays, cursor summary, subtitles settings, freeze-sync timing, and warnings. Sensitive fields are redacted by default, including storage keys, signed URLs, hashes, selectors, and raw typed text.

Use vorec editor snapshot --project <id> --at <seconds> --output frame.png when an agent needs visual readback. Use vorec editor filmstrip --project <id> --every 2 --output-dir frames to sample the whole video. Both render the same headless /render page used by export and capture exact timeline frames. Use vorec editor describe --project <id> only when the agent needs Vorec AI to analyze the source video; it spends analysis credits and writes the description back to the project.

Action controls

Narration/action segments and raw on-screen actions are separate. In editor inspect --json, each narrationSegments[] item has primaryClickIndex and clickRefs[]. Those values are indexes into clicks[].clickIndex; they are not database row IDs and they are not coordinates.

Use clicks[] / project_clicks as the source of truth for action timing and coordinates:

narrationSegments[].primaryClickIndex
        ↓ matches
clicks[].clickIndex
        ↓ owns
timestampSeconds, x, y, interactionType

That separation is intentional. A narration segment can start before or after the visible click while still pointing at the same main action.

# Read every action and how narration points to it
vorec actions list --project <id> --json

# Move the visible action marker/cursor event; narration timing does not move
vorec actions move --project <id> --click-index 7 --at 46.4

# Correct action coordinates in normalized 0-1000 video space
vorec actions update --project <id> --click-index 7 --x 386 --y 381

# Change which action is the main action for a narration segment
vorec actions set-primary --project <id> --segment <segment-id> --click-index 7

# Add a missing action and attach it to narration
vorec actions add --project <id> --segment <segment-id> --at 46.4 --x 386 --y 381 --type click --label "Save settings" --primary

# Delete an action. Use --detach when narration still references it.
vorec actions delete --project <id> --click-index 7 --detach

# Render the frame at an action timestamp for visual verification
vorec actions verify --project <id> --click-index 7 --output action-7.png

Action mutations create timeline revisions. The CLI prints an undo command, and vorec timeline undo --project <id> --revision <revision-id> restores the previous segments, project_clicks, video segments, tracks, and overlay clips.

Overlay and cursor controls

Overlay commands edit the same project_clips data the editor uses. Coordinates and sizes are normalized 0..1000 video-space values, so agents should inspect or render frames first, then place overlays against visible UI.

Supported overlay types:

• zoom — static zoom centered on --x/--y.
• follow-zoom — cursor-following zoom (cursorFollowZoom in editor data).
• blur, spotlight, callout — effect regions with --x, --y, --width, and --height.
• text, shape, image, slide, cursor — visual overlay clips on their editor tracks.

# Read existing overlays.
vorec overlays list --project <id> --json

# Add zoom or cursor-follow zoom.
vorec overlays add --project <id> --type zoom --at 12.4 --duration 3 --x 430 --y 360 --zoom-level 2.2
vorec overlays add --project <id> --type follow-zoom --at 18 --duration 4 --zoom-level 3.2

# Add privacy/attention effects.
vorec overlays add --project <id> --type blur --at 22 --duration 2.5 --x 700 --y 180 --width 220 --height 90 --mode redact
vorec overlays add --project <id> --type spotlight --at 31 --duration 3 --x 500 --y 450 --width 260 --height 160 --shape rect
vorec overlays add --project <id> --type callout --at 36 --duration 3 --x 520 --y 380 --width 220 --height 120

# Add text, shape, image, or slide overlays.
vorec overlays add --project <id> --type text --at 8 --duration 3 --text "New setting" --x 500 --y 160
vorec overlays add --project <id> --type shape --at 9 --duration 3 --shape-type arrow --x 640 --y 420
vorec overlays add --project <id> --type image --at 0 --duration 4 --image-url "https://example.com/logo.png" --file-name logo.png
vorec overlays add-image ./logo.png --project <id> --at 0 --duration 4 --x 500 --y 160
vorec overlays add --project <id> --type slide --at 0 --duration 3 --title "Setup" --subtitle "Connect your workspace"

# Move/resize/update/delete. Each clip mutation prints an undo command.
vorec overlays move --project <id> --clip <clip-id> --at 14.2 --x 480 --y 340
vorec overlays resize --project <id> --clip <clip-id> --duration 4 --width 280 --height 160
vorec overlays update --project <id> --clip <clip-id> --text "Updated label"
vorec overlays delete --project <id> --clip <clip-id>

# Cursor visibility is a project setting.
vorec cursor settings --project <id> --json
vorec cursor hide --project <id>
vorec cursor show --project <id>

Overlay mutations create timeline revisions and can be undone with the printed vorec timeline undo command. Cursor visibility updates projects.cursor_settings.show, prints an undo command, and can be restored through timeline undo because revisions now include project cursor settings.

Background controls

Background commands edit projects.video_background, the same project-level setting used by editor preview and export. Use background get or editor inspect --json to know whether a background is active before changing it.

# Read background state.
vorec background get --project <id> --json

# Add a gradient background around the recorded video.
vorec background set --project <id> \
  --type gradient \
  --gradient-start "#0f172a" \
  --gradient-end "#4f46e5" \
  --angle 135 \
  --padding 8 \
  --border-radius 18 \
  --shadow large

# Use a solid color.
vorec background set --project <id> --type color --color "#111827" --padding 6

# Use a wallpaper preset.
vorec background set --project <id> --type wallpaper --wallpaper ocean --padding 8 --shadow medium

# Add or remove the video border.
vorec background set --project <id> --border-enabled --border-color1 "#6366f1" --border-color2 "#ec4899" --border-width 3
vorec background set --project <id> --border-disabled

# Turn the background off.
vorec background disable --project <id>

Wallpaper presets are sunset, ocean, aurora, berry, forest, midnight, peach, lavender, flame, arctic, slate, and noir. Background updates are project settings, not timeline clips, but they now create timeline revisions that include projects.video_background; use the printed timeline undo command to restore the previous background.

Export controls

Export commands queue the same production export worker used by the web editor.

# Queue an export.
vorec export start --project <id> --resolution 1080p --fps 24

# Wait until completion and print a temporary download URL.
vorec export start --project <id> --wait --download-url

# Check or cancel an existing export.
vorec export status <export-id> --download-url
vorec export cancel <export-id>

Allowed resolutions are 720p, 1080p, 2k, and 4k; allowed frame rates are 24, 30, and 60.

Narration controls

Use narration commands when the agent needs to edit the voice segment itself. These commands also create timeline revisions.

# Move the voice start only. The visible action stays anchored to its click.
vorec narration move --project <id> --segment <segment-id> --at 46.4

# Move the voice and the segment's primary action together.
vorec narration move --project <id> --segment <segment-id> --at 46.4 --with-action

# Update narration copy. Existing audio is cleared so it can be regenerated.
vorec narration update --project <id> --segment <segment-id> --text "Now save the settings."

# Attach an existing action to a narration segment without making it primary.
vorec narration attach-action --project <id> --segment <segment-id> --click-index 7

# Attach and make it the main action.
vorec narration attach-action --project <id> --segment <segment-id> --click-index 7 --primary

Narration Styles

| Style | Tone | |-------|------| | tutorial | Step-by-step, clear, helpful | | professional | Polished, enterprise-ready | | conversational | Casual, like explaining to a colleague | | storytelling | Engaging, narrative-driven | | persuasive | Sales demos, investor pitches | | academic | Educational, courses, learning | | concise | Minimal, just the essentials | | exact | Neutral, factual, technical |

Claude Code Plugin

For the best experience, install the Vorec plugin for Claude Code. Your AI agent will research the codebase, generate the manifest, drive the recorder, and call the CLI for you.

1. In Claude Code, run /plugin
2. Go to Marketplaces → Add Marketplace
3. Enter: MustaphaSteph/vorec-plugins
4. Select record-tutorial and install it
5. Enable auto-update

Then just say: "record a tutorial showing how to create a project"

Why the run/analyze split?

Older versions of the CLI recorded + uploaded + analyzed in one shot. That meant burning credits on takes you might end up discarding. The current flow:

• vorec run — records locally, writes MP4 + .vorec.json sidecar with the action timeline. No network, no credits.
• You watch the MP4. Keep the good takes, delete the bad ones.
• vorec analyze <mp4> — uploads the approved take and generates narration. Credits spent only here.

Links

• Vorec — AI-narrated tutorial videos
• Vorec Recorder for macOS — Required desktop app
• Plugin repo — Claude Code plugin