# vos CLI — the complete take/capture agent reference (vos.so/llms-full.txt) The vos CLI turns a scripted browser flow into a polished product video (auto zoom, smoothed cursor, click effects, browser frame) — and every effect is DATA. You (the agent) write a flow, the CLI records + plans, you edit JSON, you re-render. The renders are deterministic: same take + same doc = same pixels. Never re-record to fix pacing or zooms — edit doc.json and render again. Install: npm i -D @vosjs/cli (one binary, one package, MIT: the engine verbs, the take pipeline AND all vos.so platform verbs. Until 0.9 the take pipeline shipped separately as @vosso/vos-plugin, and before that as @vosso/cli; both are shims now) Needs: a Chromium-family browser (system Chrome auto-detected; `npx playwright install chromium` or VOS_BROWSER_PATH otherwise) and network at encode/render time (three/mediabunny load from esm.sh in the CLI's render pages; vos.so's own pages load them from assets.vos.so). Conventions: logs → stderr, results → stdout; --json = NDJSON events ending {"event":"done",…}; exit codes 0 ok / 1 error / 2 usage-or-strict / 3 no browser / 4 the recorder met a wall (a sign-in instead of the page; see "Sessions"). vos --help prints that verb's flags and exits 0 (0.41.1 and later). A flag a verb never READ is never swallowed: the run exits 2 and stderr says "vos RAN, and ignored --x (did you mean --y?)" with the flags the verb reads. The command DID run, without that flag: fix the flag and run it again; never treat that output as what you asked for. (A push that ran has pushed.) ## The take directory (the unit of work) take/ recording.webm encoded footage (CFR WebM; recording.mp4 when a pull brought it home in that container — read the name, never assume it) frames/ screencast JPEGs — encode intermediate, deletable (~1GB at 2K) cursor.json synthesized CursorTrack (exact coords, element rects, typing pings — when/where only, never text) meta.json RecordingMeta (producer: "cli") actions.json the script that produced it — the replay recipe doc.json ProjectDoc — the editable surface (THE product artifact) vos.json hosted tracking (vos id + base version, the origin and the account it belongs to), written by push/pull/fetch ## Commands This machine (0.48 and later; no account). These four print NDJSON whenever stdout is not a TTY, and every done event carries next_step. vos setup [--agent claude,cursor,codex,copilot|all] [--global] [--no-skills] [--no-rules] [--no-browser] [--url ] [--json] Ready the computer for the loop: the vos skills into your agent's directories (npx skills add vosjs/skills -y; when skills.sh cannot be reached, the copy bundled in the package), a browser found in the recorder's order (VOS_BROWSER_PATH, system Chrome, Playwright's Chromium) or installed, ONE block between and in AGENTS.md (CLAUDE.md when only that exists; a second run replaces its own text and never yours), then doctor. Agents are detected by directory (.claude, .cursor, .codex or .agents, .github/copilot; the home forms under --global); none found ⇒ the skills land in .agents/skills. vos doctor [--url ] [--json] What is ready, in words: node, browser, ffmpeg (optional), the vos skills per agent, a credential (present or absent, never printed), and the dev server when --url names one. Exit 3 when no browser; next_step says the fix. Run it before the first record and whenever record exits 3. vos whoami [--json] the account in use (from GET /api/user/whoami: its handle, an organization's person, the key's name), which rung resolved it (--key, VOS_API_KEY, --account, VOS_ACCOUNT, the store) and every other account stored for the origin; never a key. Exit 1 when nothing resolves (recording needs no account). vos switch [] use another stored account (0.86+; with two stored and no name, the other one). vos login once per account, approving as it, stores them all. vos logout [] [--all] forget the account in use, a named one, or every stored credential (VOS_API_KEY in the shell still resolves, and the answer says so). vos create --actions actions.json [--url ] [--out take] [out.webm] [--strict] [--allow-wall] [--max-duration ] [--storage-state ] [--header name=value]... [--browser-arg=]... [--keep-frames] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--draft] [--frame ] [--background ] [--set path=value]... [--json] The one-shot verb (the vos create namespace): record + auto-plan + render in one command and one browser session. The take dir still lands on disk, so the loop below (frames → edit doc.json → re-render) stays open. With --strict an incomplete recording aborts BEFORE the render (exit 2). Use create for the first pass; use the individual verbs to iterate. vos record --actions actions.json [--url ] [--out take] [--strict] [--dry-run] [--allow-wall] [--max-duration ] [--ready dom|networkidle] [--storage-state | --session ] [--header name=value]... [--confirm ]... [--browser-arg=]... [--keep-frames] [--verbose] [--json] vos record --hosted --actions actions.json [--url ] [--out take] [--title "…"] [--folder ] [--header name=value]... [--json] vos record --app [--out take] [--seconds ] [--max-duration ] [--background ] [--json] vos record --app --actions actions.json [--out take] [--strict] [--confirm ]... [--max-duration ] [--background ] [--json] vos record --app --play play.mjs [--out take] [--max-duration ] [--background ] [--json] vos record --window … | vos record --pid … | vos record --windows Drives the page, synthesizes the cursor track, encodes, auto-plans zooms. ALWAYS pass --strict: a skipped step (a selector that never appeared, an expect that never held, a download that never came), a click on a disabled control, an await that timed out, or a take that hit --max-duration exits 2 with machine-readable skipped[], disabled[] (and capped) in the done event. A skip = broken flow — fix the selector and re-record; never ship around it. A first load that never settles is a note, never a strict failure. WHEN THE TAKE STARTS (0.79+): step 1 runs once the first page has stopped changing: after load, no DOM change for 800 ms, at most 8 s (ready: "dom", the default), because a page that holds a socket open or keeps an analytics beacon going never goes network-idle. Network idle is the opt-in ("ready": "networkidle" in actions.json, or --ready networkidle), at most 45 s. The same mode opens a setup step's goto, the page after the setup and an await's reload. The done event says how the first load settled, ready: { mode, ms, capped }; capped is a page still changing at the cap (an animation, a ticker), recorded anyway, and navTimeout: true means only that network idle was asked for and never came. EVERY STEP IS BOUNDED (0.79+): an expect by its timeout plus 5 s, an await by its timeout plus 30 s, a download by 30 s plus 30 s, any other step by its planned time plus 30 s. A page that stops answering ends the step as a skip whose reason carries the real time it took; under --strict, and always in a rehearsal, the take stops there, keeping the footage up to it. Under --json every step reports { event: "step", phase: "start", i, id, do } as it begins and phase: "end" with ms (and skipped, hung) as it ends. REHEARSE FIRST: add --dry-run to the exact command you are about to run. Every step runs against the real page, in order (a later selector usually exists only after an earlier click), but nothing is captured and nothing is written: the pointer lands instead of travelling, pauses are cut to a beat, and the take beside it keeps its footage, its cut and its script (a real re-record moves doc.json aside; a rehearsal does not). Lookups keep their whole timeout, so a miss there is a miss in the take. It prints each step with the rect it resolved, in capture px (the rects a pin or vos callout --step reads), and exits 2 on any miss (a first load that never settled is only a note). A guarded step is hovered and never pressed, so an expect or await after it is not waited on. The page's own console errors are said one line each, cut short, with a repeat counted; --verbose prints every one whole, and the done event carries them as pageErrors. A script is found broken in seconds, not after a real-time take and its encode. The Next: line it prints is the same command without --dry-run, session flags included (0.41.1 and later; an older rehearsal drops --storage-state from that line, so add it back before you paste it). Re-recording into an existing take replaces the FOOTAGE, never the cut (RK2): doc.json survives as doc.prev.json, actions.json and vos.json stay, and vos plan --reuse re-times the cut onto the new recording. vos record --reuse (0.81 and later) does both in one command, and a rehearsal of a take that has a cut puts --reuse in its Next: line. Without it the take ends with YOUR PREVIOUS CUT is kept in …doc.prev.json and the command that applies it (the done event: previousCut, next_step), and a second plain re-record keeps that cut instead of putting the untouched plan over it. A reused cut keeps its end card and any layer after the footage at the new footage's end. meta.json carries steps (when each actions step ran, source seconds); give steps an id so re-timing survives script edits. A take fetched from vos.so can be recorded again: the script rides the document (source.script) and vos fetch --media writes it back as actions.json (cli 0.70+). Recording is real-time. --max-duration (default: the hosted cap, read live from GET https://vos.so/api/limits → limits.recordingMaxSeconds, 1800 = 30 min today; the built-in 1800 applies offline): the capture stops there and the done event says so (capped: true, the remaining steps did not run); with --strict that exits 2. A take longer than 30 min is refused by vos push (413), so cut the flow, not the cap. --app (0.88+): A DESKTOP APP, NOT A PAGE? (macOS 14 and later.) vos record --app records ONE app's window while you, or your agent's computer use, work the app. Without --actions there is NO SCRIPT: the take is what was performed, so start it, do the thing, and end it (Ctrl-C or a signal; or give its length up front with --seconds ). --window names one window; vos record --windows lists every window that can be recorded, with its id, app and size. The window is recorded alone: every other window is kept out of every frame (a notification, an app that opens over it), the capture follows the window if it moves, and the system pointer is NOT in the pixels. The pointer's path, its presses and where typing happened are in cursor.json, in the window's own points, so vos plan zooms on them as on a page take and the studio draws the cursor. What was typed is never recorded. The footage is recording.mp4; meta.json says captureSurface "app" and producer "desktop", names the app (never a window title), and carries cornerRadius, which rounds the card to the window. A performed take has no actions.json and no steps, so nothing re-records it, and --strict, --dry-run, --reuse and --hosted do not apply: cut it from its digest (vos digest), like any recording someone performed. The PERMISSIONS are macOS's and belong to the app the CLI runs from (the terminal, the editor, the agent host), not to vos. Screen Recording is required: without it the verb stops, in words that say where to switch it on (a person does that; an agent asks). With Accessibility as well, a press carries the bounds of what was pressed, so its zoom fits the control; without it a performed take still has its pointer, presses and typing. vos doctor has a desktop line with both. --app --actions (0.89+): THE SAME WINDOW, SCRIPTED. The actions.json a page's take runs drives the app through accessibility while its window is recorded: vos record --app "" --actions actions.json --out take --strict. A script that names "app" (in place of "url") needs no --app, and "viewport" is then the size the window is given first, in points. LOOK FIRST: vos look --app "" [--out look] [--json] writes look.png (the window as a take shows it) and lists every control with ONE proposed selector, UNIQUE or AMBIGUOUS; nothing is pressed. SELECTORS are a role, then what the element is called or its accessibility identifier: button[name='Save'], textfield[id='title'], button[name*='Share'] (contains), toolbar > button[name='Share'] (> a child, a space any descendant), button[name='Delete']:nth(1), *[id='sidebar']. Take a UNIQUE one as it is; the identifier comes first because it survives a redesign, and an AMBIGUOUS one names by position. STEPS a desktop take runs: wait, hover, click (count, button "right", modifiers), type (replace, at, focus), press (Mod is Command), scroll, move, drag (tx, ty) and expect (selector, text, gone, enabled, timeout), with id, zoom, payoff, caption, read, guard and ms as on a page; x and y are the window's points. REFUSED before anything is recorded, each in words: url, ready, peers, the steps paste, download, await, an expect on js, and a drag path, and (0.93+) a selector that is not one in this dialect (button[name^='Save']: = and *= are the two tests), so vos validate actions.json refuses it when the script is read and not at its step. Where a page would await, give an expect a timeout. MASK ON A DESKTOP TAKE (0.93+): "mask": [{ "selector": "popup[name*='Account']" }] covers every element a selector matches BEFORE a frame is encoded, with one flat colour taken from the edge of what it covers, so what was under it is in no file; the done event's masks says how many elements each covered, and one that matched nothing is a note. An element's bounds are read about thirty times a second, so something that appears or moves mid-take is covered from the next reading: have what must never show on screen before the take begins. as: "text" is a page's and is refused. SETUP AND TEARDOWN ON A DESKTOP TAKE (0.93+): the page's verbs (wait, click, type, press, if), pressed through the same driver OFF CAMERA. setup puts the app where the take starts; teardown undoes what a take or a walk left (the text it typed, a panel it opened), and runs after a take that stopped early and after vos look --actions --until too. Open a teardown with an if on what only a leftover has, so a clean app says "nothing to undo"; a list has ONE if, and what follows it is skipped when it is not there. A setup that misses records nothing; a teardown that misses is reported and never fails the take. AN APP THAT IS AN ACCOUNT has no throwaway instance: record it only when its person asked, say what the picture will hold of theirs and mask what is left, guard the one step that spends, and record a result that arrives later as TWO takes joined (vos join), the wait read off camera with vos look. A MISS STOPS THE TAKE (0.90+): a step whose element never appears, an expect that never holds, or a disabled control (reached, NOT pressed) ends the take there, exit 1, with the step and the reason in the done event's stopped. The steps after a miss were written for a state the app is not in, and their keys would land wherever focus is: in a file tree, Enter renames. "onSkip": "continue" at the top of the script goes on as a page's take does, and --strict then exits 2 on the miss; ALWAYS pass --strict. Put an expect between a beat that opens something and a beat that types into it. TYPING CHECKS WHERE THE KEYBOARD IS (0.90+): before the first key of a type, the take asks what has focus and refuses, with nothing typed, to type onto a row, a button or anything else where a key is a command. A type may leave selector out with "focus": false to type where the keyboard already is (an editor the app draws and names no field for, after a click or a chord has put focus there), and a new line in text is the Return key, so a few lines are ONE step. WHICH WINDOW (0.90+): --app picks the largest window of that name, and two instances of one app share a name. vos record --windows prints each window's process; --pid records, or looks at, that process's window. NEVER script an app a person has open with real work: start a throwaway instance (its own profile directory, a scratch project, settings that switch off what moves by itself) and aim at its pid. ELECTRON AND CHROMIUM APPS build their accessibility tree only when asked, and a running one can take minutes: vos look --app waits ten seconds and says so when it is not there (kind and built in --json). Started with --force-renderer-accessibility, such an app has it from the first frame. THE SCREEN A CLICK OPENS (0.90+): vos look --app "" --actions actions.json --until [--confirm ]... runs the script up to and including that step, FOR REAL (the app's controls are pressed), then looks, and keeps no take; exit 2 when the step was not reached. vos look --app also says when the outline carries a file path the picture does not show. The take keeps actions.json and meta.steps (in the window's points), so pins, anchors, vos plan --zooms per-beat and vos plan --reuse work as on a page take. WHAT IT TAKES: the app comes to the front and the REAL pointer and keyboard are used, so nobody and nothing else may use the machine until the take ends (say so to the person first), and there is NO --dry-run and no --hosted, because a rehearsal would press the app's real controls. If another app takes the keyboard mid-take, typing stops there and the take stops: a script's text never lands in another app. What was typed into a field is never read; vos look --app does read what the interface calls its elements, which can include content shown as text (a message, a file's name), and that stays on this machine. Accessibility is REQUIRED for a scripted take and for vos look --app (a person grants it; an agent asks). A menu-bar menu is not in the window: reach it with its key chord. --app --play (0.94+): THE SAME WINDOW, PLAYED BY A PROGRAM. A script is a list, and a list cannot play what answers back: a game, a chart that moves, a drag that depends on where something landed. vos record --app "" --play play.mjs --out take records the window while your module drives it. play.mjs: export const take = { app: 'Google Chrome', viewport: { width: 1280, height: 800 } } export default async function (play, { window }) { await play.step('start', () => play.click("button[name='Play']")) await play.step('fly', async () => { /* look, decide, act */ }, { zoom: false, payoff: true }) } take (optional) is a desktop script's head: app, viewport, mask, setup, teardown, and no steps. play has click(selector | {x, y}), type(text, { selector }), press(keys), move(x, y, ms), find(selector, timeoutMs), gone(selector, timeoutMs), sleep(ms), now() (the take's seconds) and send (the driver's own command, checked by nothing). click and type keep a script's rules: an element is waited for, a disabled control is not pressed, nothing is typed where keys are commands. Whatever the program throws ENDS THE TAKE (exit 1, with the step it was in), and such a take is not cut. play.step(id, fn, marks) names a stretch as one step of the take (meta.steps, do "play"), which captions, pins and the plan hold on to; marks are zoom (false = PLAY, watched whole: the planner proposes nothing over it and no zoom reaches into it), payoff (true = the film's payoff) and caption. The module is your own code and runs as you; no --dry-run, no --seconds, never with --actions. window is the window's size in points. To read a page's state, start the throwaway browser with --remote-debugging-port and READ over it; never write state to make the picture. A LONG TASK IS ONE TAKE (0.94+): wait inside the take ({ "do": "expect", "gone": "button[name='Stop']", "timeout": 1200 }, or await play.gone("button[name='Stop']", 20 * 60_000), with --max-duration above the wait). A window that stands still costs about 7 KB a second; an app that is working about 120 (eighteen minutes, 130 MB). A wait looks again when the window cannot be read for a moment, up to its own deadline. From 0.95 a wait or an expect may carry "zoom": false: the wait is watched whole and the planner proposes nothing over it ("zoom": true on one is refused). In doc.json, segments drop the middle and a speed span (up to 16) runs what is kept; vos digest looks INSIDE the wait (0.95+, GLANCE moments, below), so the cut has frames to choose from. The machine is taken for the whole wait: say so, or record two takes and join them. THE SCREEN: a take that waits sends no input, so the system would sleep the display and lock. The helper holds the display awake for the length of a take (@vosjs/driver 0.4.1 and later); BETWEEN takes nothing does, so keep it awake yourself for a film with a long wait (caffeinate -d). Behind a locked screen a script is refused ("The screen is locked") and only a person can unlock it. SEVERAL APPS, ONE FILM: one take per app (each window its own stage), then vos join a b c --out film --captions. Step captions sit at the top for a take pressed in its lower third (0.94+, a chat's composer), and a rejection on a later take is measured against that take's own length. ONE LOOK: apps follow the system's light or dark appearance. A desktop take says which it was made under (meta.appearance, driver 0.4.1), and vos validate and vos join warn when a film's inputs were recorded under both (0.95+): read it before every take, not once. --hosted (0.49+): NO BROWSER HERE? A cloud agent, a CI runner or a chat host records on vos.so instead. The same script goes up (POST /api/record/jobs), the fleet records, plans and lands the take as a PRIVATE vos with its doc.json and its digest, and the take comes home into --out with its media (vos fetch --media), the directory every other verb reads. Needs a credential (vos login, or VOS_API_KEY). What travels: the script, the viewport, every --header value (a preview's bypass token) and the value of every { "env": "NAME" } a setup step reads, from this shell, for the job's life; the platform stores the script with the values stripped and never the env or the headers. What never travels: a session (--session and --storage-state are refused; a Cookie header is refused by the platform), because none of a person's ever reaches vos.so. A page behind a sign-in fails on the fleet in words naming the ladder below, exit 4, and the empty vos it would have landed on is taken down; a private-network URL (localhost, 10.x, a .local name) is refused before a job exists, so a dev server needs a tunnel or a preview deployment. The fleet records up to 10 minutes at 1280x720 by default (viewport in actions.json, 640..1920 wide); 20 hosted takes per account per day. --dry-run stays a local act. --title and --folder name the landing. Refused before a job exists, in words (the platform answers 400 with kind "invalid"): a guarded step (nobody can confirm a spend on the fleet), a download (a hosted take has no outputs/ to keep a file in), a paste (a fleet browser has no clipboard) and a drag whose path names a file (the script travels alone, so the points ride inline: vos record --hosted 0.79+ writes a path file's points into the script it sends, and a script posted by hand must carry them). A hosted take records the sound the page played in meta.media and places no clip for it, since it has nowhere to keep the file. AWAITS COME OUT OF THE FOOTAGE: an await's wait is wall time the footage cap never counts, and the whole job must finish within 13 minutes, so the footage cap is the least of the 10 minutes and what the job has left after 2 minutes of room and every await's timeout (600 s each when unset): one await with no timeout leaves 1 minute of footage. The recorder stops there (capped: true, and the version's note names the cap), and the 202 answers cap { seconds, shortenedByAwaits }. A script whose awaits would leave under 30 s of footage (more than 630 s of timeouts in all) is refused in words: give the awaits shorter timeouts, or record it on this machine. THE WALL CHECK (0.41 and later): once the first navigation settles, and before a frame is captured, record, create and --dry-run ask whether the recorder landed where it was sent. Refused with exit 4 and a sentence ("asked for /dashboard, landed on /login: no session for app.acme.com"): the URL answered 401/403, the recorder was sent to an identity provider or a sign-in path, or the page is a sign-in form rendered in place. A redirect somewhere else with no sign-in in sight (a site that shows strangers a public page) is refused under --strict and in a rehearsal, and only warned about otherwise. Nothing is recorded and nothing is cleared: a re-record's old footage survives a refusal. Exit 4 is never a script bug: do not touch actions.json, walk the ladder in "Sessions". --json carries a wall event (kind, level, asked, landed, refused). --allow-wall records the page anyway (a video OF a sign-in page is a legitimate take); meta.wall and the digest's take.wall then say so, and a digest that prints WALL is footage of the wrong page: re-record it with a session before cutting it. WHAT THE FRAME SHOWS (0.42 and later): after the page opens and after every step the recorder reads the text visible in the viewport and reports the KIND of sensitive-looking thing it saw and where, never the string: email (an address, except on example.com or a .test/.example/ .invalid/.localhost domain, which is what demo data should use), key (sk_live_, ghp_, github_pat_, xoxb-, AKIA, vos_sk_, a JWT), card (13 to 19 digits passing Luhn), card-tail (•••• 4242). A rehearsal ends with the list, so read it BEFORE you record; it also rides the done event's exposures[], meta.exposures[] ({step, kind, selector, rect, seen}; step -1 = as the page opened), vos validate warnings and the digest's take.exposures. Warnings, never failures: a product may show addresses on purpose. The selector reaches that element and no other, so it pastes into a mask. NOTICES (0.79+), information beside the exposures and never a warning, never in exposures[] and never a --strict failure: the signed-in account's own name (read from where apps say whose account it is: a "Signed in as …" line, an account menu's label or button), with every place in the frame it showed, and a list of the account's recent items (a "Recents", "Recent" or "History" heading over three or more links) with the one-line mask that hides it. They land in meta.notices[] ({ step, kind: "account-name" with places and sure, or "personal-list" with heading, selector, rect, items; seen }), the record and create done events, the end of a rehearsal and a noticed section of vos validate . The name itself is never printed, not even inside a selector. THE SOUND A PAGE PLAYS (0.79+): every