Docs / CLI

Clipy CLI: your recordings from the terminal

@clipy/cli lists, searches, and reads your screen recordings without a browser: transcripts (including SRT/VTT subtitle export), AI summaries, key moments, MP4 downloads, and the full agent-context bundle, and records new ones from the terminal, headless or as a live session. Zero dependencies, Node ≥ 18.

Giving this workflow to an agent? Start with the canonical /agents.md contract, then use clipy guide --json for the exact installed command schema.

1. One-command setup

One command wires Clipy into your coding agent, with no API key to copy or paste:

npx @clipy/cli@latest setup claude   # also: codex · cursor · windsurf · opencode

Swap claude for codex or cursor. The first time you run it:

1. 1.Your browser opens at clipy.online. You click Approve once; the page names the client and the exact scopes it grants: read your recordings and record and upload.
2. 2.The Clipy skill installs into your agent's skills directory.
3. 3.Your agent records with Clipy, and reads any recording back: transcripts, summaries, and key moments.

The approval mints a scoped, revocable API key and stores it in ~/.config/clipy (mode 0600). You can see and revoke it any time under Settings → API keys.

Prefer to wire it up by hand?

npm install -g @clipy/cli   # or run ad-hoc: npx @clipy/cli <command>
clipy login                 # opens the browser approval; --key <key> to paste one instead

clipy login runs the same browser approval on its own. Already have a key? Mint one at clipy.online/settings/api-keys (shown only once, looks like clipy_sk_live_…) and paste it with clipy login --key. Prefer no stored state? Set CLIPY_API_KEY or pass --key per command. Precedence: flag → env → stored config.

On SSH or a display-less box, clipy login switches automatically to a copy-code flow (also forceable with --no-browser): it prints an approval URL to open on any device (laptop or phone) and after you click Approve, paste the one-time code back into the waiting terminal.

On Windows, if the approval page says “This authorization link is invalid”, you are on a CLI older than 0.13.0, which let cmd.exe cut the link at its first &. Run npm install -g @clipy/cli@latest and log in again, or use clipy login --no-browser to approve from any device.

2. Commands

The first group creates recordings; the rest read them. Every recording-reading command accepts either the bare public id (3kelcef8wo8h) or the full https://clipy.online/video/<id> share URL.

record and session capture a headless browser by default. Add --source mac-screen to record your actual Mac screen through the Clipy desktop app must be running, and the first capture asks for your consent in-app. Target one window or display with --window "Chrome" or --display <id>: run clipy sources to list the ids.

3. Scripting

--json prints the raw API response on every read command. Exit codes: 0 ok · 1 error · 2 usage · 3 artifact not ready yet, so scripts can branch on processing state.

# Newest recording's id
clipy list -n 1 --json | jq -r '.recordings[0].id'

# Export subtitles for a recording
clipy transcript 3kelcef8wo8h --srt > recording.srt

# Stop a recording, then block until Clipy finished transcribing
clipy wait 3kelcef8wo8h --for both && clipy summary 3kelcef8wo8h

An agent can discover the whole CLI instead of guessing it: clipy guide --json emits every command, flag, exit code, and env var as a self-describing manifest. The full agent-integration story (recording lifecycle, capture targets, headless/CI, and what is not supported yet) starts at /agents.md and has a browsable reference at /docs/agents.

Skill, CLI, or MCP?

The Clipy skill is the default for public pasted links. The CLI is for you: terminals, shell scripts, CI. MCP is for authenticated agent workflows: private library search and inline tool results. clipy mcp bridges the two by launching the MCP server directly.