The zoomcap CLI

Record your screen from the terminal in one command — 60fps native capture, system audio, and pixel-exact click tracking that becomes automatic cinematic zooms in the editor. This is the full reference.

Overview#

The zoomcap CLI is part of ZoomCap Pro. It captures your screen with Apple’s native ScreenCaptureKit engine, records system audio and your mic in sync, and tracks every click and keystroke timing while you work. When you stop, it hands the recording to the editor at zoomcap.live over localhost, where those clicks and keystrokes are already turned into zooms.

Nothing installs permanently and nothing uploads: npx runs the recorder, the file lands in your ~/Movies/ZoomCap folder, and editing plus export happen in your browser on your machine.

Requirements#

• macOS 15 or newer — for the native 60fps recorder with system audio and menu-bar control. Older macOS falls back to an ffmpeg recorder (video + optional mic, no system audio).
• Node 18+ — npx ships with Node. If you write JavaScript you already have it.
• Apple Silicon or Intel — the recorder ships as a universal binary — both are supported.
• A ZoomCap Pro plan — the CLI checks your subscription on each run. Not on Pro? Record free in the browser instead.

Install & first run#

There is nothing to install. One command downloads the recorder, runs it, and cleans up after itself:

The very first run does three things in order: signs you in (a browser tab opens), asks macOS for permissions, then starts a countdown. Grant the permission prompts, run the command again, and you’re recording. Check your setup any time with:

Sign in & Pro#

The CLI is gated behind sign-in and an active Pro plan. The gate runs before any capture starts, so a billing or sign-in hiccup can never cost you a recording you already made.

How sign-in works

On first run the CLI opens zoomcap.live/cli-auth in your browser. Sign in there and click Connect terminal — that hands a session back to the CLI over a one-time localhost channel. Your session is cached in ~/.zoomcap/auth.json (readable only by you) and refreshes itself, so you sign in once and forget about it.

The Pro check

After sign-in, the CLI asks the server whether your account is on Pro. The server is the source of truth — the check happens on every run, so upgrading or cancelling takes effect immediately. If you’re offline, a previously verified Pro session keeps working for up to 72 hours so flaky wifi never blocks a recording.

Commands#

Add -h / --help for the built-in help, or -v / --version for the version.

record options#

Examples

During a recording#

Permissions#

macOS prompts for these on the first run. Grant them, restart the terminal if asked, and record again — they stick from then on.

• Screen Recording — required — to capture the screen.
• Accessibility / Input Monitoring — required for auto-zoom — this is how the CLI sees when and where you click and type. Without it, recording still works but there are no automatic zooms.
• Microphone — optional — the recording never waits on it. If it isn't granted, you get screen + system audio and can add your voice next time.

The permission is attributed to your terminal app (Terminal, iTerm, Ghostty…), not to a separate ZoomCap app — so you grant it once, to the terminal you use. npx zoomcap doctor names exactly what’s missing and how System Settings lists it.

Auto-zoom#

While you record, the CLI notes three things — all as timings, never content:

• Clicks — position + time. Each becomes a zoom centred on what you clicked.
• Typing — time only. Typing pulls a zoom to where the text appears (inferred from your last click) and holds it while you write.
• Scrolling — time only. Scrolling keeps an active zoom held — reading while zoomed-in never makes it snap back.

These are clustered into smooth zooms that hold while you work and release when you pause. Want a zoom somewhere specific? Press ⌃⌥Z mid-recording to drop a mark, or add, re-aim, and delete any zoom in the editor afterwards.

Audio#

On macOS 15+ the recorder captures system audio and your mic natively and in sync — no virtual drivers, no Soundflower, no second take because you forgot to route audio. Control it with:

• Default — screen + system audio + mic.
• --no-mic — screen + system audio, no microphone.
• --no-audio — silent, no system audio and no mic.

Files & handoff#

Each recording lands in its own timestamped folder under ~/Movies/ZoomCap (or your --out path):

When recording stops, the CLI serves the files on a localhost port and opens zoomcap.live/import pointing at it. The editor pulls the video over 127.0.0.1 — a secure loopback connection — and jumps straight to editing. Used --no-open? The import link is printed; open it whenever, or drag the files onto /import later.

Capture and export are both MP4 with H.264 — the compatibility-first master that plays in browsers, Slack, and social uploads. If you need a WebM sibling for a website embed, a vertical social cut, or a GIF for a README, derive those from the master rather than re-recording. Settings by channel are in Best video format in 2026: MP4, MOV, WebM compared.

Privacy#

• Keystroke timing only — the recorder captures WHEN you typed, never WHICH keys. No key codes, no characters are recorded or written to disk — a recording can't leak what you typed, even though the CLI holds an Input Monitoring grant.
• Nothing is uploaded — footage stays on your disk, hands to the editor over localhost, and encodes in your browser. There is no server to trust and no render queue.
• Your files are yours — product demos, tutorials, client work — no restrictions, no watermark on Pro.

Troubleshooting#

“Permission denied” when running npx

An old cached build. Update and clear the npx cache:

If it persists, force-clear the cache with npm cache clean --force and try again.

The recorder won’t start / no zooms appear

A missing permission. Run npx zoomcap doctor — it names exactly what’s missing. Screen Recording being off stops recording; Accessibility / Input Monitoring being off means recording works but auto-zoom can’t see your clicks. Grant them in System Settings → Privacy & Security, restart the terminal, and record again.

“Couldn’t verify your ZoomCap plan”

The CLI couldn’t reach the server to confirm Pro. Check your connection and retry. A recently verified Pro session works offline for up to 72 hours; past that, you need to reconnect once.

The editor never opened

Your files are safe in ~/Movies/ZoomCap. Keep the terminal open until the editor loads, or use the printed import link. You can always drag screen.mp4 and zoomcap.meta.json onto /import.

Stuck on “finalizing” after stop

Finalizing a long or high-resolution recording flushes the encoder to disk and can take a few seconds — longer on a low-RAM machine. Let it finish; the editor opens as soon as it’s done.

Sign out & reset#

There’s nothing installed to remove. To sign out and clear the cached session:

That deletes ~/.zoomcap/auth.json. Your recordings in ~/Movies/ZoomCap are untouched — delete that folder yourself if you want the space back.

Support#

Hit something this page doesn’t cover? Run npx zoomcap debug and include its output — it captures your macOS version, the capture engine, and the last recording’s stats, which is usually enough to pinpoint the issue.