Skip to content
VersioncamVersioncam

Commands

Source README.md · versioncam 0.5.3 from npm

Every command works in the directory that holds versioncam.config.ts: run it from there, or name that directory with --cwd. npx versioncam --help prints the same list.

Set up

Section titled “Set up”

Once per machine, and once per repository.

versioncam install                 the headless Chromium this version of versioncam records with
    --with-deps                    and its system libraries (Linux CI)
    --full                         and the full browser, which login and preview open
versioncam init                    install the authoring skill into .claude/
    --into <dir>                   into <dir>/versioncam/ instead, for another host
    --force                        overwrite files that are already there
versioncam doctor                  check this machine can record, and that the app starts
versioncam login                   sign in once and save the browser session

Write

Section titled “Write”

Look at the page before writing against it.

versioncam inspect <path>          what a clip can click, and where each name came from
    --json                         machine-readable
versioncam measure <path> <sel>    where a selector's matches are, and what they say
versioncam dsl                     the clip DSL: every method, its options and defaults

Record

Section titled “Record”

check is the CI command. It does not render: a clip that no longer matches the app fails while it records, at the step that no longer exists. A video of the wreckage would help nobody.

versioncam record [id…]            drive the app and capture frames
    --draft                        15fps at CSS scale: cheap, for writing clips
versioncam check [id…]             record every clip; exit 1 if any breaks
    --report <file>                and write each clip's result there, as JSON
versioncam stability [id…]         record each clip twice the same way; stable or not
    --runs <n>                     how many times (default 2)
    --full                         at full quality rather than draft

Review

Section titled “Review”

Look at what a recording shows, and check what needs no eyes.

versioncam sheet <id>              an eight-frame contact sheet
    --at-marks                     sample the beats instead of even spacing
versioncam frame <id> <n>          one frame at output size, to a png
    --t <seconds>                  pick the frame by time instead
    --at <label>                   or by the beat it shows
versioncam review <id>             the checks that need no eyes; PASS/FAIL, exit 0/1
    --beats <file>                 [{ label, expect }] the clip promised
    --min <s> --max <s>            duration bounds (default 9 and 11)
versioncam preview <id>            open the scrubber in a real browser
    --scene <id>                   preview a scene instead
    --frame <n>                    start at this frame

Output

Section titled “Output”

Turn recordings and scenes into video.

With no ids, render renders every recording in .versioncam/recordings/, and stale ones are recordings too: a draft or a trial run, or a clip since renamed or deleted, stays there until its directory is deleted. It renders every scene as well. Ids choose among recordings and scenes alike, by substring, as they choose clips for record. --scene names a scene exactly, and it renders whatever the ids are. Without ids, the scenes it names are the only scenes rendered. An id that matches nothing, or a --scene the scenes module does not define, stops the command before anything renders.

versioncam render [id…]            composite and encode recordings and scenes
                                   no ids: every one, stale recordings included
    --scene <id>                   and this scene, whatever the ids say (repeatable)
    --sequence                     stitch the results into one piece
    --report <file>                and write what it made there, as JSON

Publish

Section titled “Publish”

Send what the last run recorded to version.cam, which renders it and keeps it at a living address. publish records nothing and renders nothing: for each clip the config defines, it sends the recording if the clip’s last run passed, or the failure if it did not, so version.cam knows when a clip broke (see When a clip breaks). Only the states the service has not seen are uploaded, so a version that changed one screen sends one screen.

It needs a credential in the environment, never on the command line: VERSIONCAM_OIDC_TOKEN, which the versioncam GitHub Action requests from GitHub for the run (no secret to store), or VERSIONCAM_TOKEN, a project token from version.cam for a repository outside GitHub (see Other CI). VERSIONCAM_API points it somewhere other than https://api.version.cam. Outside GitHub Actions it reads the commit and branch from git; VERSIONCAM_COMMIT and VERSIONCAM_BRANCH set them outright.

versioncam publish [id…]           send the recordings and their checks to version.cam
    --dry-run                      print what would be sent, and send nothing
    --report <file>                and write the living URLs there, as JSON

Manage

Section titled “Manage”

What version.cam knows about a project, and its settings, from the command line: what the dashboard shows and does, once you have signed in with a code you approve in a browser. A setting changes only when you approve that one change in the browser too. These need no versioncam.config.ts, and run anywhere in a clone of the repository. See From the command line.

versioncam cloud login             sign in to version.cam, with a code you approve in a browser
    --label <name>                 what the approval page calls this machine
versioncam cloud logout            sign out: revoke the token, and delete it
versioncam cloud status [project]  each clip, current or broken, and what plays meanwhile
versioncam cloud failure <clip>    why a clip broke, and its picture, into .versioncam/failures/
versioncam cloud ack <clip>        "I know, keep the old one": the reminders stop
versioncam cloud embed <clip>      the snippets that embed a clip, and its files
versioncam cloud set <name> <val>  change a setting, once you approve it in a browser:
                                   visibility public|unlisted|private, retention <days>|off,
                                   viewers on|off, alerts email|slack <address>|off,
                                   alerts issues on|off
versioncam cloud plan [account]    the plan, and the pages to upgrade and pay on
    --project <owner/repo>         which project, when not this repository's
    --json                         machine-readable, for status, failure, embed and plan

From another directory

Section titled “From another directory”

In a monorepo the app is one directory among many. A command run from somewhere else, the repository root or a subdirectory of the app, can name the app’s directory. The config, .env.recording and .env, .versioncam/ and any relative path are then that directory’s. --cwd can go anywhere on the line.

npx runs the versioncam it finds in the directory it is run from, or in the nearest one above it, never in one below. From above an app that has versioncam in its own node_modules, it runs another copy, or downloads the latest. So --cwd refuses a directory whose own versioncam is not the one running, and says to cd into it instead.

versioncam <command> --cwd <dir>   as if run in <dir>, which holds versioncam.config.ts
versioncam --version               which versioncam this is