Vidova CLI

vidova records your screen into a Vidova tape (.vtape) and sends it to a Vidova project. When the project's timeline has no clips yet, the web editor puts the recording on it as a screen recording with its cursor, clicks, keys and camera.

Install

You need Node.js 20 or later, pnpm, and a C++ toolchain for the recorder addon.

cd cli
pnpm install
pnpm build:native   # builds ../native, the recorder the desktop app ships, for this Node
pnpm build          # bundles out/index.js
npm link            # optional: puts `vidova` on your PATH

The CLI loads the first recorder addon it finds, in this order:

1. VIDOVA_NATIVE_RECORDER, a path to a MediaRecorder.node
2. cli/build/Release/MediaRecorder.node, from pnpm build:native
3. the @vidova/<platform>-<arch> package
4. native/build/Release/MediaRecorder.node, the desktop app's build

An addon that exists but does not load is an error. The CLI does not try the next one.

On Linux, read docs/linux-build.md for the system packages and for X11 and Wayland capture.

ffmpeg is needed for takes with a microphone but no screen audio track, and for the stream details in vidova info. The CLI uses VIDOVA_FFMPEG_PATH and VIDOVA_FFPROBE_PATH when set, then ffmpeg and ffprobe on your PATH, then the binaries of the optional @ffmpeg-installer packages.

Sign in

vidova login

The terminal shows a code and opens https://vidova.ai/cli/auth. Sign in to Vidova in that browser, check that the code matches, and select Connect. The terminal then holds its own Firebase session in ~/.vidova/session.json (mode 600). It refreshes the session by itself.

vidova whoami    # the account and origin this terminal uses
vidova logout    # removes the saved session

To use a local web server, point the CLI at it:

vidova origin http://127.0.0.1:47310
vidova origin --reset    # back to https://vidova.ai

VIDOVA_ORIGIN sets the origin for one command. FIREBASE_AUTH_EMULATOR_HOST sends the token calls to the Firebase Auth emulator.

Record

vidova                                   # pick the screen, mic, camera and project, then record
vidova record --no-prompt --display 1 --duration 30
vidova record --no-prompt --window Safari --mic "MacBook" --cam FaceTime

Press p to pause or resume and q (or Ctrl+C) to stop. The tape goes to ~/.vidova/recordings/ unless you pass -o <path>. --raw keeps a plain .mp4 instead of a tape.

To send the take to Vidova when it is saved:

vidova record --upload                        # to your default project
vidova record -p <project-id>                 # to a project
vidova record --new-project "Launch video"    # to a new project

--no-timeline leaves the timeline alone. --no-open does not open the project in the browser. The CLI checks the sign-in and the project before the recording starts, so a problem shows up before the take and not after it.

Recording defaults:

vidova config                  # shows the keys and what is set
vidova config fps 30
vidova config output-dir ~/Videos
vidova config --reset

--fps, --width, --countdown and --keys on the command line win over vidova config.

When a take is cut off

A take records into its own folder in ~/.vidova/takes/ with a take.json that says what is being recorded and how far it got. The folder becomes a tape when the take stops, and is then removed.

• Ctrl+C, q, --duration, a closed terminal window (SIGHUP) and a shutdown or logout (SIGTERM) all stop the take and save it in full, with its cursor and key tracks.
• A crash in the CLI stops the recorder first, so its files are finished, and saves the tracks before the process exits.
• When the disk holding the takes has less than 500 MB free, the take stops and is saved. The dashboard warns below 2 GB. A take does not start below 500 MB.
• A Ctrl+C while the take is being saved asks for a second press. The second press quits and leaves the take for vidova recover.

If the process is killed outright (kill -9, a power cut), the screen file still plays up to its last fragment, a second or two before the cut: the recorder writes it in fragments (setFragmentedOutput in native/, used only by the CLI). The cursor and key tracks live in the recorder until the take stops, so they are lost in that case. The dashboard says crash-safe when the recorder addon writes fragments. An addon built before that says it is not.

vidova recover               # repairs every cut-off take into a tape
vidova recover --list        # what is waiting, and whether it is crash-safe
vidova recover <take-id>     # one take
vidova recover --discard <take-id>

vidova (record) says when earlier takes are waiting. A recovered take goes where the take would have gone (-o, the output folder, --raw).

Send a tape to a project

vidova projects list
vidova projects create "Launch video"
vidova projects default <project-id>     # uploads go here when no --project is given
vidova upload take.vtape --project <project-id>
vidova upload take.vtape --new-project "Launch video" --wait

upload also takes a plain video (.mp4, .m4v, .mov, .webm, .mkv). A plain video has no cursor or key tracks. --wait waits until Vidova has processed the video. --json prints the result for scripts.

Every upload goes in parts through upload.vidova.ai, three at a time:

• A part that fails (a dropped connection, a timeout, HTTP 408, 425, 429 or 5xx) goes again alone, after 1, 2, 4, 8, 15, 30, 30 and 60 seconds.
• A part link that expired is asked for again.
• Each part's SHA-256 is checked against what the server stored. A part that arrived changed goes again.
• Ctrl+C stops the upload and keeps what went up. A second Ctrl+C quits at once.

What an upload has sent is kept in ~/.vidova/uploads/. Running vidova upload on the same file carries on to the same project and sends only the parts that are not in yet. If the server dropped the upload (it expired), that track starts again.

vidova upload take.vtape              # carries on if an earlier run stopped
vidova upload --resume                # carries on with every unfinished upload
vidova upload take.vtape --dry-run    # what would be sent, with nothing sent
vidova upload take.vtape --no-keys    # leaves the key track out
vidova upload take.vtape --no-cursor  # leaves the cursor track out

How a recording reaches the timeline

Web projects live in the browser that made them. The CLI cannot read them. The pieces fit together like this:

1. The web app publishes its project list (ids and names) to /api/cli/projects. vidova projects list reads that list.
2. A project the CLI makes is added to your browser's list the next time Vidova opens there.
3. vidova upload asks the Vidova media API for an upload URL for each of the screen and camera videos, sends each file in one PUT, and then tells the API the upload is complete. That starts the video's processing.
4. The CLI then records a delivery at /api/cli/deliveries. It holds the two uploads, the tape's cursor and key tracks, and whether the recording may go on the timeline.
5. The editor takes in the project's deliveries when the project opens, and every 20 seconds while its tab is visible. It links the cursor, keys and camera to the screen video, as a dropped tape is linked. If the timeline has no media clips, the recording goes on it at the start.
6. If the editor cannot take a recording in, for example because its video was deleted, the delivery is marked failed with the reason, and the editor shows that reason.

The server refuses a delivery for a project that is not in your project list. The CLI checks this before it uploads anything.

Tape tools

vidova info take.vtape [--json]
vidova extract take.vtape -o ./take
vidova extract-file take.vtape screen.mp4
vidova pack screen.mp4 --camera camera.mp4 --cursor cursor.json --keyboard keyboard.json -o take.vtape
vidova devices [--json]
vidova permissions

A .vtape is an uncompressed tar. It holds manifest.json, screen.json with files/screen, and when present camera.json with files/camera, cursor.json and keyboard.json. The layout is the one in app/src/main/recording-tape/pack.ts, so the desktop app and the web editor open the same file.

Terminal output

The recorder asks its questions as steps along a line at the left of the terminal. Each answer stays on screen above the next question, and long lists scroll. While it records, one compact block shows the time, file size, mic level and the keys. vidova --help groups the commands and shows examples.

• NO_COLOR=1 turns colour off. FORCE_COLOR still wins over it.
• The Linux console and older Windows consoles get ASCII symbols instead of Unicode ones.
• Spinners and upload progress go to stderr and only show in a terminal. Logs and pipes get the final lines only.
• --json output does not change.

The look lives in theme.ts (colours and symbols), ui.ts (plain commands), components/Rail.tsx (the recorder's steps) and help.ts (help and usage errors).

Privacy

• Keys: a take keeps shortcuts only by default (--keys shortcuts): combos with Cmd, Ctrl or Alt/Option held, and Return, Delete, Space and C on their own, which is what the editor shows. Plain typing and letters typed with only Shift are dropped before the take is saved, so a password or a message typed while recording is not in the tape. --keys all keeps every key (for typing sounds on every press). --keys off and --no-keyboard keep none. vidova config keys <mode> sets the default.
• Keys pressed while a take is paused are never kept, on every platform.
• ~/.vidova/recordings, takes, uploads and logs are 0700, and tapes and journals are 0600, so other accounts on the computer cannot open them. A folder made by an older version with wider permissions is narrowed.
• Logs are kept for 14 days.
• vidova upload --dry-run shows what a tape would send. --no-keys and --no-cursor leave those tracks out.

Files and settings

Everything lives in ~/.vidova, or in VIDOVA_HOME when it is set:

| File | What it holds | | --- | --- | | session.json | the terminal's sign-in | | origin.json | the origin set with vidova origin | | projects.json | the default upload project for each account | | defaults.json | vidova config values | | last-setup.json | the devices you picked last, offered as a quick start | | recordings/ | tapes | | takes/ | takes being recorded, and takes cut off before they were saved | | uploads/ | what each unfinished upload has sent | | logs/ | one log file per day, kept for 14 days |

A settings file that does not parse is an error with the file name. It is not ignored.

Other variables: VIDOVA_KEEP_RAW=1 keeps the recorder's scratch files, VIDOVA_LINUX_SESSION picks x11 or wayland-portal, and VIDOVA_LINUX_DEBUG=1 shows the addon's log on stderr.

Develop

pnpm typecheck
pnpm test

The tests write tapes and open them with the web and desktop unpackers, run the sign-in and upload flow against the real /api/cli routes with fake Firebase and media servers, and check the order of the recorder calls.

esbuild bundles web/lib/cli/protocol.ts and the tape schemas from app/src/shared into out/index.js, so the CLI and the server parse the same shapes. The server side is in web/server/routes/cli.ts, web/server/cli/, web/lib/cli/ and web/components/cli-auth-page.tsx. It needs FIREBASE_SERVICE_ACCOUNT_JSON, VITE_FIREBASE_API_KEY and VIDOVA_API_URL, and it keeps its state in three server-only Firestore collections: cliDeviceAuthorizations, cliProjectDirectories and cliDeliveries.

Changes from 2.x

• Tapes are .vtape files. The .screencast format is gone. vidova pack makes a tape from a video.
• vidova login approves the terminal in the web app at /cli/auth. A session saved by 2.x does not work. Run vidova login again.
• Uploads go to web projects, and the editor places the recording.
• mcp, mcp-install, timeline, generate, components and the old import are gone. Vidova's MCP server is at mcp.vidova.ai.
• --project-name with --create-project still works. It means --new-project.