CLI reference

The sonvo command reads, shares and records Sonvo videos from a terminal. Output is plain text by default and JSON with --json, for scripts and AI agents.

Install

curl -fsSL https://www.sonvo.co/install.sh | sh

The script picks the build for your computer (macOS, or Linux on x86_64 or arm64) and installs it to /usr/local/bin when that's writable, otherwise to ~/.local/bin. It tells you if that folder isn't on your PATH yet. To choose the folder:

curl -fsSL https://www.sonvo.co/install.sh | SONVO_INSTALL_DIR=~/bin sh

With Sonvo for Mac, you can also choose Install command line tool from the app's account menu. It links the tool that ships inside the app into /opt/homebrew/bin, or ~/.local/bin.

Sign in

sonvo login
sonvo whoami

sonvo login opens your browser to sign in and receives the sign-in back on this computer (it waits up to five minutes). On a Mac it's kept in the Keychain; on Linux in ~/.config/sonvo/<host>.token, readable only by you. sonvo logout signs this computer out: it revokes the token on the server, so any copy of it stops working too, and then forgets it. You can also revoke it from Signed-in apps in the account menu on the website.

Without a browser, set SONVO_TOKEN instead (see For AI agents). --server <url> or SONVO_SERVER points the tool at another Sonvo server; the default is https://www.sonvo.co.

Global options

list

sonvo list [--folder <name|id>] [--workspace <name|id>] [--limit N] [--json]

Your videos, newest first (50 unless you set --limit). --folder narrows to one folder; --workspace lists a team workspace's shared videos instead. Also sonvo ls.

[
  {
    "id": "3f9c21a0b4d1e2f3",
    "title": "Checkout walkthrough",
    "url": "https://www.sonvo.co/v/3f9c21a0b4d1e2f3",
    "status": "ready",
    "duration_ms": 84000,
    "created_at": "2026-10-22T07:12:44Z",
    "views": 4,
    "comments": 2,
    "visibility": "link",
    "transcript": "ready"
  }
]

get

sonvo get <id|link> [--md | --transcript | --json]

A video's title, summary, chapters and comments. It works for any video you can open, including private ones you own and workspace videos you can see. Times follow the video as people watch it, after edits. Also sonvo show.

• --md prints the whole video as Markdown for AI, with the text of attached files.
• --transcript prints just the transcript, one timed line each ([m:ss] text). Add --json for segments.
• --json prints everything as JSON.

{
  "id": "3f9c21a0b4d1e2f3",
  "url": "https://www.sonvo.co/v/3f9c21a0b4d1e2f3",
  "title": "Checkout walkthrough",
  "status": "ready",
  "owner": "Maya",
  "created_at": "2026-10-22T07:12:44Z",
  "duration_ms": 84000,
  "views": 4,
  "summary": "Maya walks through the new checkout...",
  "chapters": [{ "start_ms": 0, "title": "Cart" }],
  "transcript": {
    "status": "ready",
    "segments": [{ "start_ms": 0, "end_ms": 4200, "text": "Here's the new checkout." }]
  },
  "comments": [
    { "id": 12, "at_ms": 61000, "author": "Sam", "text": "Love this", "created_at": "2026-10-22T08:01:10Z" }
  ],
  "files": [
    { "id": 7, "name": "qa-report.pdf", "kind": "pdf", "size": 21084,
      "url": "https://www.sonvo.co/v/3f9c21a0b4d1e2f3/a/7",
      "text_url": "https://www.sonvo.co/api/v/3f9c21a0b4d1e2f3/a/7/text" }
  ],
  "agent_markdown": "https://www.sonvo.co/v/3f9c21a0b4d1e2f3/agent.md"
}

A comment that's a reaction has reaction (the emoji); a reply has reply_to (the comment's id). A video with a button has call_to_action with label and url. In files, url downloads the file (a link's own address for links; HTML pages have none), and text_url returns its readable text as JSON when there is some.

open

sonvo open <id|link>

Opens the video in your browser.

comment

sonvo comment <id|link> "Fixed in PR #42" --at 1:05

Adds a comment, pinned to a moment when --at is given (as the video plays, after edits). JSON: {id, video, at_ms, text}.

rename

sonvo rename <id|link> "New title"

Renames your video. Its AI title won't replace yours afterwards. JSON: {id, title}.

delete

sonvo delete <id|link> [--yes]

Deletes your video and its recording for good, and the link stops working. It asks first unless --yes; without a terminal, --yes is required. Also sonvo rm. JSON: {id, deleted}.

upload

sonvo upload <video file> [files to attach...] [--title T] [--json]

Uploads a video (mp4, mov, m4v, webm or mkv) and prints its link. Files after the video are attached to it.

• MP4, MOV, M4V and WebM files up to 50 MB go up as they are. Longer videos, and MKV files, are cut into streaming chunks first, which needs ffmpeg (brew install ffmpeg).
• The thumbnail comes from ffmpeg when it's installed, otherwise from Quick Look on a Mac.
• --title sets a title the AI won't replace. Without it, the video starts with the file's name and gets an AI title.

The transcript, title and summary follow within a minute.

{
  "id": "604f3d5cc266e99d",
  "url": "https://www.sonvo.co/v/604f3d5cc266e99d",
  "title": "Release demo",
  "duration_ms": 12100,
  "files": [{ "id": 24, "name": "notes.md", "kind": "text" }],
  "failed": []
}

share

sonvo share <file> [more files...] [--title T] [--link URL --name N] [--json]

Shares files on their own, with one link: PDFs, HTML pages (shown in a safe preview), images, code, notes, or any file up to 50 MB. People can comment, and agents read every file's text at the link's /agent.md. Without --title, the share is named after the first file.

A PDF's words are included when pdftotext is installed (brew install poppler). Otherwise they're added the first time you open the share in your browser.

{
  "id": "f8271c26fe2ee376",
  "url": "https://www.sonvo.co/v/f8271c26fe2ee376",
  "title": "Checkout QA",
  "files": [
    { "id": 18, "name": "qa-report.html", "kind": "html" },
    { "id": 22, "name": "Sonvo repo", "kind": "link" }
  ],
  "failed": []
}

If some files can't be added, the rest are still shared, the problems are listed in failed, and the exit code is 1.

attach

sonvo attach <id|link> <file> [more files...] [--link URL --name N] [--json]

Adds files, or a link, to one of your videos or shares. They show on its page and in its Markdown for agents. JSON: {id, url, files, failed}.

record

sonvo record start [--mode screen|screen+cam|cam|screens] [--screens] [--window <app or title>] [--area x,y,w,h] [--title T]
sonvo record stop [--no-open]
sonvo record pause | resume | status | discard

Drives Sonvo for Mac, which has to be installed and signed in. The tool opens the app if it isn't running.

• start returns once the countdown is done and capture has begun, with the video's link (already live). Without --mode, it records in the mode chosen in the app.
• --window records one app's window, by app name or window title. --area records part of the screen, in points from the top-left of the main display, like 0,0,1280,720.
• --screens (or --mode screens) records all your displays at once; the video follows your cursor between them.
• --title sets a title the AI won't replace.
• stop returns the link and length and opens the video, unless --no-open. The transcript, title and summary follow within a minute.
• discard deletes the recording in progress and its link.
• sonvo record on its own is status.

The first time, the app asks whether to let apps on this Mac control it. You can change the answer later with Allow command line control in the app's account menu.

start   {"share_id": "14ef01bea697a197", "link": "https://www.sonvo.co/v/14ef01bea697a197", "state": "recording"}
stop    {"share_id": "14ef01bea697a197", "link": "https://www.sonvo.co/v/14ef01bea697a197", "duration_ms": 31206}
status  {"state": "recording", "paused": false, "elapsed_s": 12, "mode": "screen", "signed_in": true,
         "email": "[email protected]", "server": "https://www.sonvo.co", "share_id": "...", "link": "..."}

state is idle, recording, paused or busy. Recording needs a Mac; the other commands work on Linux too.

whoami and logout

sonvo whoami [--json]   # {server, id, email, name}
sonvo logout [--json]   # {ok, server, revoked}

logout revokes this computer's token and forgets it. A sign-in made with a version of sonvo before 0.3 can't revoke itself; logout says so, and you can revoke it from Signed-in apps on the website. With SONVO_TOKEN set, commands keep using that token after a logout.

Exit codes

0 it worked, 1 it failed, 2 bad usage, 3 not signed in, 4 not found, 5 refused (not allowed, busy, or the free plan's limit). Details in For AI agents.