Command Line Reference

Command line reference

Every command takes the dataset folder as its first argument. Commands exit with status 1 on an error (validate and check-video also do when they find problems), so they work in scripts and CI.

init

Create an empty dataset.

vidlabel init path

argument
path	required

info

Show what is in a dataset.

vidlabel info path [options]

argument
path	required

option	default	what it does
--json	off	Print one JSON document instead of text (for programs and agents).

validate

Check a dataset against the spec. Exit code 1 if there are errors.

vidlabel validate path [options]

argument
path	required

option	default	what it does
--deep / --no-deep	off	Also decode every mask and cross-check its box.
--json	off	Print one JSON document instead of text (for programs and agents).

build

Compile the sorted training table; prints the release id to pin.

vidlabel build path [options]

argument
path	required

option	default	what it does
--include-rejected / --no-include-rejected	off	Also put rejected annotations in the release.
--json	off	Print one JSON document instead of text (for programs and agents).

add-video

Probe a video file with ffprobe and register it, with its frame index.

vidlabel add-video path video_file [options]

argument
path	required
video_file	required

option	default	what it does
--video-id	none	Id to register it under. Default: the file name without extension.
--no-hash	off	Skip hashing the file (faster, weaker identity).
--no-index	off	Skip the frame index (timestamps and keyframes; see vidlabel index).

index

Make (or rebuild) the frame index of registered videos: per-frame timestamps and keyframes, read without decoding.

vidlabel index path video_ids... [options]

argument
path	required
video_ids	optional

option	default	what it does
--video-path	none	Video file, if the recorded path is stale (one video only).
--root	none	Folder(s) to search for the videos by file name.
--force / --no-force	off	Rebuild indexes that already exist.
--no-verify	off	Do not check the file's hash against the registered one (faster).

derive-view

Copy the whole-frame rows that lie inside a view (frames, region, labels) into that view. Safe to run again.

vidlabel derive-view path video_id view_id [options]

argument
path	required
video_id	required
view_id	required

option	default	what it does
--label	none	Only these labels (repeat for several).
--origin	none	Only rows with these origins (repeat for several).

tracks

List the tracks of a video: label, frames, how many rows, mean confidence and review status of each.

vidlabel tracks path video_id [options]

argument
path	required
video_id	required

option	default	what it does
--view	none	Tracks made in this view (default: whole-frame rows).
--json	off	Print one JSON document instead of text (for programs and agents).

review

Approve or reject whole tracks at once.

vidlabel review path video_id [options]

argument
path	required
video_id	required

option	default	what it does
--track	none	Track id to change (repeat for several).
--status	none	unreviewed, approved or rejected.
--view	none	The track was made in this view (default: whole-frame rows).

add-labels

Add labels to the shared vocabulary.

vidlabel add-labels path labels...

argument
path	required
labels	required

add-view

Define a crop and/or time ranges of a video.

vidlabel add-view path view_id video_id [options]

argument
path	required
view_id	required
video_id	required

option	default	what it does
--region	none	x,y,width,height in displayed pixels
--frames	none	first,last frame (inclusive); repeat for several time windows
--output-size	none	width,height the crop is resized to, if resized
--labels	none	comma-separated labels allowed in this view

preview

Draw the annotations on frames of the real video, to check they line up. Needs OpenCV (the video extra).

vidlabel preview path video_id [options]

argument
path	required
video_id	required

option	default	what it does
--out	preview_out	Output folder.
--frames	none	e.g. '0-100,250'. Default: a spread of annotated frames.
--every	1	With --frames, keep every Nth frame.
--view	none	Show this view's crop and only its annotations.
--mp4 / --no-mp4	off	Write one MP4 instead of PNG images.
--video-path	none	Video file, if the recorded path is stale.
--root	none	Folder(s) to search for the video by file name.
--color	none	Box colour: 'red', '#ff8800' or '255,136,0' for all labels, or per label: 'person=red;car=#00ff00'. Default: one colour per label.
--thickness	none	Box line width in pixels. Default: scales with the video.
--font-scale	none	Label text size, e.g. 0.8. Default: scales with the video.
--labels / --no-labels	on	Write label text next to boxes.
--outline / --no-outline	on	Dark border around boxes and text.

check-video

Check that the video file on disk matches the metadata, and report how costly random access is (keyframe spacing).

vidlabel check-video path video_id [options]

argument
path	required
video_id	required

option	default	what it does
--video-path	none	Video file, if the recorded path is stale.
--root	none	Folder(s) to search for the video by file name.
--hash / --no-hash	off	Also verify the content hash (reads the whole file).
--seek / --no-seek	off	Also test that random-access seeking returns exactly the right frames (decodes the whole video once).

cache

Save the frames a training run will use as image files, so random access is a file read. The cache is derived data: delete and rebuild it any time. Pass it to FrameSamples(cache=...).

vidlabel cache path out [options]

argument
path	required
out	required

option	default	what it does
--release	latest	Release to take the frames from: 'latest', a release id, or 'none' for the live annotations.
--view	none	Only the frames this view samples.
--frames	annotated	'annotated' (frames with annotations) or 'all'.
--format	jpg	'jpg' (small, slightly lossy) or 'png' (exact pixels, larger).
--quality	95	JPEG quality, 1-100.
--root	none	Folder(s) to search for the videos by file name.
--overwrite / --no-overwrite	off	Re-decode frames that are already cached.

query

Print the annotations of one video as JSON (ids are strings; mask pixels are left out). For scripts and agents.

vidlabel query path video_id [options]

argument
path	required
video_id	required

option	default	what it does
--kind	none	box, mask or marker.
--label	none	Only this label.
--status	none	unreviewed, approved or rejected.
--origin	none	human, model, imported, ...
--track	none	Only this track id.
--frames	none	A frame range such as 100-200.
--view	none	Rows made in this view (default: whole-frame rows).
--limit	100	At most this many rows.
--offset	0	Skip this many rows first.

mcp

Serve the dataset to an AI agent over MCP (standard input and output). The agent can read and propose, never commit.

vidlabel mcp path [options]

argument
path	required

option	default	what it does
--name	agent	Who the agent is; its proposals are made by 'agent:NAME'.

ui

Open the local web interface. Needs pip install "vidlabel[ui]".

vidlabel ui path [options]

argument
path	optional

option	default	what it does
--host	127.0.0.1	Address to listen on. The default is this computer only; use 0.0.0.0 to share on your network.
--port	8765	Port. If it is busy the next free one is used.
--no-browser	off	Do not open a browser window.
--fs-root	none	Only allow the file picker inside this folder (repeat for more). Required for file access when sharing.
--token	none	Use this access token instead of a random one (so a shared address stays the same).

schema

Print (or write) the JSON Schema of the spec.

vidlabel schema [options]

option	default	what it does
--out	none	Write the JSON Schema to this file instead of printing it.

---

Source: docs/cli.md