For AI agents
All docs
Developers and agents
For AI agentsCLI reference

For AI agents

Sonvo is built for people and AI agents to hand each other work. Every video reads as text, and agents can share files, upload videos and record through the sonvo command.

Read a video

Add /agent.md to any video link to get it as Markdown: title, length, summary, chapters, the timed transcript, comments, and the text of attached files.

Terminal
curl https://www.sonvo.co/v/<id>/agent.md

On the video's page, Copy for AI copies the same text to paste into Claude or ChatGPT. For private and workspace-only videos, use the CLI signed in as someone who can see the video:

Terminal
sonvo get <link> --md      # the same Markdown
sonvo get <link> --json    # structured: summary, chapters, transcript segments, comments

Sign in as an agent

On a computer with a browser, sonvo login is enough. For CI and agents without a browser, set SONVO_TOKEN to a token from a signed-in machine. On a Mac, after sonvo login:

Terminal
security find-generic-password -s tech.benmore.sonvo.cli -a www.sonvo.co -w

A token acts as your account, so keep it secret. Tokens don't expire on their own: to cut one off, open Signed-in apps in the account menu on the website and revoke Sonvo command line. Everything signed in to your account is listed there, apps and browsers, each with a button to revoke it.

Send work to the user

Terminal
sonvo share report.html results.csv --title "Checkout QA" --json
sonvo upload demo.mp4 notes.md --json
sonvo attach <id> screenshot.png --link https://github.com/org/repo/pull/42

HTML is shown in a sandboxed preview, so a self-contained page (inline CSS and JS) is the best way to send a report.

Record the screen

Only when the user asks. Recording needs Sonvo for Mac running and signed in.

Terminal
sonvo record start --mode screen --title "Bug: export button"
# ... do or show the thing ...
sonvo record stop --no-open

The first time, the app asks the user whether to let apps on this Mac control Sonvo from the command line. Their answer sticks, and they can change it in the app's account menu. Recordings started this way show "Started from the command line" on the control bar while they record. If you get exit code 5, ask the user to allow it.

About a minute after stopping, sonvo get <id> --json has the transcript and the AI title.

Exit codes

CodeMeaning
0It worked
1It failed (network, server, or part of a batch)
2Bad usage: a missing argument, a bad flag or a file that doesn't exist
3Not signed in. Run sonvo login or set SONVO_TOKEN
4Not found, or you can't see it
5Refused: command-line control isn't allowed, or the app is busy

With --json, a failure prints {"ok": false, "error": "...", "code": "..."} as well as setting the exit code.

Rules of thumb

  • Use --json for anything you parse.
  • Never delete or discard without the user asking. sonvo delete needs --yes when there's no terminal.
  • sonvo help agents prints this guide in the terminal.