Commands, options and automation

How to use commands

Run commands from a terminal or an external agent.

Start with capturefab COMMAND --help. Use capturefab COMMAND SUBCOMMAND --help for a nested command.

Running capturefab without a command opens the desktop app. Other commands do not open it.

Camera commands use the only running session automatically. With multiple sessions, select one with --session NAME.

Where supported, a camera command can use a temporary worker when no session runs. Use --direct --camera ID to choose this explicitly.

Local output paths belong to the calling terminal. Named destination paths belong to that destination.

Use one number and unit for durations, such as 30s, 5m or 1.5h. File sizes accept values such as 512MiB and 2GiB.

capturefab gui --name bench
# Run subsequent commands in another terminal:
capturefab --session bench connect sim:0
capturefab --session bench --camera sim:0 capture -o shot.png
capturefab --session bench status --json

JSON and errors

--json returns one {version, ok, result} object, or {version, ok, error} on failure.

Progress and diagnostics go to stderr. Read error.code before deciding whether to retry.

For assistant run, exit 0 can also mean needs_user. Read the result before treating the task as finished.

A request timeout can occur after the session accepts a command. Read status before sending the same write again.

Installed builds can have different optional features. Use doctor --json, schema --json and installed help to confirm availability.

Global options

These options apply before or after the command.

Boolean flags are off unless supplied. They take no value.

--help or -h shows command help. --version or -V shows the executable version.

Environment defaults: CAPTUREFAB_CAMERA, CAPTUREFAB_SESSION, CAPTUREFAB_ACTOR, CAPTUREFAB_ACTOR_KIND and CAPTUREFAB_HWACCEL.

CAPTUREFAB_EFFICIENCY supplies efficiency mode. For desktop launches, the saved Performance setting follows the environment default.

CAPTUREFAB_DATASET supplies --dataset for GUI, serve, capture and recording commands.

Find cameras and sources

Find available sources and examine their capabilities.

Task guide: Find cameras and sources.

capturefab discover

Find cameras, document scanners and cameras on saved hubs. Aliases: list and cameras.

Aliases: list, cameras.

capturefab network-scan

Examine GigE network paths. In a session, tune connected cameras that are not busy.

capturefab scanners

List document scanners using the platform scanner driver.

capturefab native

List host-driver cameras (AVFoundation, V4L2, DirectShow).

capturefab onvif

Discover/resolve ONVIF camera profiles and RTSP stream URIs.

capturefab onvif discover

Find ONVIF cameras on the network.

capturefab onvif resolve

Resolve an ONVIF media profile to its stream URL.

capturefab compatibility

Show available connection routes for a camera model, including HDMI capture devices.

Read and change camera settings

Control the addressed camera and its live acquisition.

Feature names and ranges come from the camera. Some features are locked during live acquisition.

CLI set writes sequentially. Use RPC set_many for an atomic group with one undo checkpoint.

Task guide: Read and change camera settings.

capturefab info

Show camera identity and readable features.

capturefab features

List camera features, access, values, units and limits.

capturefab get

Read the named camera features.

capturefab set

Write FEATURE=VALUE assignments in order. A failure can leave earlier assignments applied.

capturefab execute

Execute a camera command, such as TriggerSoftware. Camera commands cannot be undone.

capturefab start

Start live acquisition in a persistent session.

capturefab stop

Stop live acquisition in a persistent session.

capturefab auto

Enable automatic exposure, gain and frame-rate control for the addressed camera.

capturefab manual

Stop automatic control. Hold current values, or use --revert to restore pre-auto values.

capturefab undo

Undo the latest reversible camera change in an existing session.

capturefab redo

Redo the latest undone camera change in an existing session.

capturefab history

Show the next undo and redo labels for the selected or addressed camera.

capturefab xml

Print the GenICam XML from a connected camera.

capturefab memory

Read or write camera registers for protocol debugging. These writes bypass ordinary feature validation.

capturefab memory read

Read the specified camera register range.

capturefab memory write

Write hexadecimal bytes to the specified camera register. This cannot be undone.

Capture images and manage schedules

Save images now or at scheduled times.

Use PNG, JPEG, raw, PGM or PPM. A known filename extension selects the format; folders and stdout default to PNG.

-o - writes one image to stdout. Omit --json for binary output; this capture uses a temporary worker.

Schedules remain active while their GUI, headless session or direct process runs. They are not restored after exit.

Task guide: Capture images and manage schedules.

capturefab capture

Save one or more images. Existing files are never overwritten.

capturefab jobs

List capture schedules in a persistent session.

capturefab cancel

Cancel a scheduled capture job on the selected camera.

Record and forward video

Record a bounded file or send video to another service.

A file recording defaults to a 512 MiB limit. Set enough space for the requested duration.

With --duration, the CLI waits and the camera worker stops the encoder at the deadline. Ctrl-C stops it early.

Without a duration, session recording returns immediately. Direct recording runs until Ctrl-C. Use status before retrying a timed-out request.

Task guide: Record and forward video.

capturefab forward

Record to a file or send video to a stream URL. The record alias has identical behavior.

Aliases: record.

capturefab stop-forward

Stop the current recording or forwarded stream on the addressed camera.

capturefab ffmpeg

Inspect bundled FFmpeg, codecs and supported protocols.

Sessions and shared activity

Open a workspace and control it from other processes.

gui and serve run in the foreground. Keep their process open while other CLI calls use the session.

Each camera has its own worker. Set --camera explicitly when multiple people or agents share a session.

Browser access has no separate login. Everyone who can reach the HTTP listener can control its session.

Task guide: Sessions and shared activity.

capturefab gui

Open the desktop app and its local automation session.

capturefab serve

Run a headless session in the foreground. Add --listen to enable the browser client and HTTP API.

capturefab sessions

List local GUI and headless sessions.

capturefab connect

Connect the named camera in a running session.

capturefab select

Set the session default camera for CLI calls that omit --camera.

capturefab disconnect

Disconnect the addressed camera in a running session.

capturefab status

Show the state of an existing persistent session.

capturefab activity

Read shared session activity. Optionally wait for its revision to change.

capturefab rpc

Send a SessionCommand JSON object from stdin to an existing session.

Datasets and exports

Catalog captured files, add notes and export analysis data.

One session holds one open dataset. Close it before switching files or changing its size policy.

--file reads a dataset outside the session. Use it only when another process does not hold that file.

Task guide: Datasets and exports.

capturefab dataset

Catalog captures and recordings in a DuckDB dataset and export analysis bundles.

capturefab dataset open

Open or create the session's dataset; existing files are never overwritten.

capturefab dataset close

Checkpoint and close the session's dataset.

capturefab dataset status

Show the session's dataset, or summarize --file.

capturefab dataset note

Add a timestamped note (shift handover, defect, setup change).

capturefab dataset query

Run one read-only SELECT; --file reads a dataset no session holds.

capturefab dataset export

Write data files, manifest.json and README.md into a new folder.

Saved destinations

Save folder destinations for captures and recordings.

Choose a folder on your disk, a removable drive or a mounted network drive. Removing a destination leaves its files in place.

Task guide: Saved destinations.

capturefab destination

Manage saved folders on your disk, removable drives or mounted network drives.

Aliases: destinations.

capturefab destination list

List saved destinations.

capturefab destination add-folder

Save a folder destination, such as a directory on an external drive or network share.

capturefab destination remove

Remove a saved destination.

capturefab destination test

Test whether a destination is reachable and writable.

capturefab volumes

List mounted external, removable and network volumes. On macOS and Linux, read-only volumes, such as mounted disk images, are omitted; Windows lists every drive.

Saved setups

Save a tuned camera's settings by name and restore them later, with a preview of what changes.

A setup is kept on this computer in setups/ in the state directory. Restoring one is a single camera change that undo reverts, and a failed restore puts every value back. Setups never read or write the camera's own user sets.

Task guide: Saved setups.

capturefab setup

Save, list, preview, restore, delete and import saved setups. save, diff and apply need --camera or --session.

Aliases: setups.

capturefab setup save

Save the camera's current writable settings under a name. Values a firmware auto drives, network and user-set settings are left out and listed under skipped.

capturefab setup list

List saved setups with their camera, date and value count, and the folder that holds them (dir). A file that cannot be read, such as a damaged one, one from a newer Capturefab or a copy named differently from its file, is listed under its file name with status (unreadable or newer_version) and reason. A newer_version file needs a newer Capturefab: using it exits 5 (unsupported). Using an unreadable one exits 3, and setup delete removes it.

capturefab setup show

Show a saved setup's values. With --json it prints the setup document; redirect it to a file to back up or share the setup.

capturefab setup diff

Compare a setup with the camera and print what restoring it would change, what it cannot apply and whether the stream restarts. Changes nothing.

capturefab setup apply

Restore a setup as one camera change. It previews first; changes to settings outside the known image settings, such as triggering and I/O lines, need --yes. A setup changed after its preview is refused.

capturefab setup delete

Delete a saved setup, including one setup list shows as unreadable. The camera is not changed.

capturefab setup import

Save a setup document from a file, such as one written by setup show NAME --json.

Storage and retention

Set file retention limits and inspect storage usage.

The default policy allows 10 GiB and 10,000 owned files, then stops new output. Reservations count toward these limits.

Delete-oldest affects eligible Capturefab-owned files. Existing unrelated files and modified files are not deleted.

Storage task workspaces contain a database and its write-ahead log. Copy both together before removing an orphan workspace.

Task guide: Storage and retention.

capturefab storage

Show owned file usage and reserved recording space.

capturefab storage status

Show global policy, owned files and reservations.

capturefab storage task-data

Review or remove retained task workspaces, including after a restart.

capturefab storage task-data list

List durable workspaces and whether their owner has released them.

capturefab storage task-data copy

Save the database and WAL together into a new ordinary folder.

capturefab storage task-data remove

Permanently remove one orphan workspace and release its reservation.

capturefab storage configure

Persist the global storage ceiling for all cameras and future sessions.

Resource limits

Set local CPU and camera-buffer limits.

These limits apply across local Capturefab processes. They are separate from the disk storage policy.

Thread changes affect future image work and new codecs. Ongoing recordings keep running.

Task guide: Resource limits.

capturefab resources

Show resource use or change CPU and camera-buffer limits.

capturefab resources status

Show the current limits, use and remaining capacity.

capturefab resources configure

Change the named limits. Omitted limits keep their values.

capturefab resources reset

Restore automatic CPU and camera-buffer limits.

Camera hubs

Save hub connections and discover their cameras.

Save Home Assistant, Frigate, go2rtc or UniFi Protect access here. Credentials belong to the process that opens the camera.

With remote browser control, hub cameras also need serve --allow-hubs. Removing a hub does not remove its secret unless requested.

Task guide: Camera hubs.

capturefab hub

Save Home Assistant, Frigate, go2rtc and UniFi Protect servers and open their cameras as hub:NAME/CAMERA.

Aliases: hubs.

capturefab hub list

List saved hubs.

capturefab hub cameras

List cameras on one saved hub, or on all of them; each ID is a --camera selector.

capturefab hub test

Examine that a saved hub answers and accepts its secret.

capturefab hub add-home-assistant

Save a Home Assistant hub. Camera IDs use hub:NAME/camera.ENTITY.

Aliases: hub add-ha.

capturefab hub add-frigate

Save a Frigate NVR. Use port 5000 without authentication, or port 8971 with a user.

capturefab hub add-go2rtc

Save a go2rtc hub. Camera IDs use hub:NAME/STREAM.

capturefab hub add-unifi-protect

Save a UniFi Protect snapshot source. Create its API key in the console’s integration settings.

Aliases: hub add-unifi.

capturefab hub remove

Remove a saved hub; --forget-secret also deletes its saved secret.

Camera sign-ins

Save user names and passwords for password-protected RTSP and ONVIF cameras.

Sign-ins are saved in the OS credential store under service capturefab-camera; camera-logins.json in the state directory lists addresses and user names only. The camera worker uses a saved sign-in for any credential-free camera with that address. A camera that asks for a sign-in fails with auth_required and one that refuses it with auth_rejected, both exit 1. Builds without the credential store refuse add and remove with exit 5.

Task guide: Camera and media source locators.

capturefab login

Save user names and passwords for rtsp://, rtsps:// and ONVIF cameras in the OS credential store.

Aliases: logins.

capturefab login add

Check a camera sign-in, then save it in the OS credential store.

capturefab login list

List saved camera sign-ins (never their passwords).

capturefab login remove

Forget a saved camera sign-in and delete its password.

Virtual camera servers

Serve test images through GigE Vision, RTSP or ONVIF.

Presets: gige (640 × 480, 30 fps), rtsp (1920 × 1080, 30 fps), onvif (1280 × 720, 15 fps), vision (640 × 480, 60 fps).

H.264 dimensions must be even. A media folder is read one level deep, in filename order, without following symlinks.

Task guide: Virtual camera servers.

capturefab simulate

Host virtual GigE Vision, RTSP or ONVIF cameras using looping test data.

capturefab simulate presets

Show camera presets and their integration use cases.

capturefab simulate run

Host a virtual camera until Ctrl-C (or --duration).

Tools for external agents

Read tool schemas and execute checked tool calls.

Use a file for the plan or arguments when --secret-stdin reads a secret. Both inputs cannot share stdin.

Use the catalog below for every tool. Read its schema with tools describe NAME --json before constructing arguments.

Every argument key is necessary. Use JSON null where the schema permits a default.

Set the camera inside args.camera; omit global --camera and CAPTUREFAB_CAMERA for tool calls.

The CLI writes inspection images to private temporary files by default. Use --image-out for a budgeted saved file.

Action dry runs return normalized commands without executing them. Plans hold 1–64 calls and at most 256 KiB.

Calls run in order. A failure stops the plan; earlier effects remain. Human approval must cover the exact disruptive action.

Task guide: Tools for external agents.

capturefab tools

List, examine and run shared image and data tools for people and external agents.

capturefab tools list

List shared image and data tools, risks and portable argument schemas.

capturefab tools describe

Read one tool's description and argument schema without a session.

capturefab tools call

Read session facts or examine and run one image or data tool.

capturefab tools apply

Examine and run a version 1 image and data tool plan in order.

Built-in assistant

Set provider access, plan tasks and run tasks within limits.

The optional ai build feature provides these commands. Provider setup is separate from an external agent’s own model access.

ask returns a plan. run performs a task and enforces its camera scope and limits.

Images and dataset rows have separate permissions. Supervised mode asks before each change; autonomous mode allows routine changes within limits.

Ctrl-C stops new work. Already accepted camera commands can finish; read the task report for remaining work.

Task guide: Built-in assistant.

capturefab assistant

Configure an AI provider, plan captures or run a bounded camera task.

Apple Intelligence

Select apple_foundation_models to use the fixed on-device system model. No API key, endpoint or reasoning-effort setting applies.

The provider needs macOS 26 or later, an eligible Mac, Apple Intelligence enabled and its model ready. The build must include the native helper.

Use assistant test apple_foundation_models to test it. Camera-image input and test --vision are unsupported.

Requests stay local with no remote fallback. Existing tool approvals, task scopes and limits still apply.

See local model setup and troubleshooting.

capturefab assistant providers

List providers, credential readiness and image support without making a request.

capturefab assistant use

Select a provider and save its non-secret settings.

capturefab assistant key

Save or remove a provider key in the OS credential store.

capturefab assistant key set

Read one key from stdin and save it in the OS credential store.

capturefab assistant key remove

Remove the saved key; environment credentials are unchanged.

capturefab assistant test

Send a small tool round trip to the selected provider.

capturefab assistant ask

Read observations and return an editable plan. Changes run only with --apply and the allowed tools.

capturefab assistant run

Run a camera task inside the specified camera scope, approval policy and limits.

capturefab assistant runs

List local assistant action logs, including unfinished tasks.

capturefab assistant log

Read one local assistant action log.

Workflows

Validate or run ordered session commands from a JSON file.

Files use version 1 with 1–256 steps and a 1 MiB limit. All steps are validated before execution.

Apply needs a running session. A failure stops later steps; earlier effects remain.

Relative paths resolve beside the workflow file. For stdin, paths resolve from the calling terminal’s folder.

Task guide: Workflows.

capturefab workflow

Validate and apply repeatable multi-camera setup, capture and recording plans.

capturefab workflow validate

Validate every step and show the resolved plan without contacting cameras.

capturefab workflow apply

Apply ordered steps to a persistent session; stop on the first failure.

Diagnostics and command help

Read capabilities, the automation schema and shell help.

Task guide: Diagnostics and command help.

capturefab doctor

Report this computer’s camera, storage and acceleration capabilities. Each warning includes a suggested action.

capturefab version

Print this build's version and what the last update check found, without a network request. capturefab version --check reads https://capturefab.com/releases.json once and reports the newest release, its download for this computer and its SHA-256. It never changes the desktop app's automatic setting or skipped version.

capturefab schema

Emit the versioned CLI and session automation contract as JSON.

capturefab completions

Generate completion definitions for bash, zsh, fish, PowerShell or Elvish.

capturefab help

Print this message or the help of the given subcommand(s).

Tool catalog

Read the purpose and arguments of every shared camera and data tool.

Each row below documents a tool and every top-level argument. The installed schema gives nested fields, permitted values and numeric limits.

Tool argument limits can be stricter than CLI limits. Do not reuse CLI limits without reading the tool schema.

A call can have a higher risk class when it affects other work. Read its dry-run result before execution.

Observe tools read state. Reversible tools change settings. Bounded tools create limited output. Disruptive and HumanOnly actions ask for approval.

inspect_frame accepts fresh 0–10, a preview edge of 0 or 256–1,568, and an optional normalized region.

wait_for accepts timeouts from 1s to 10m. It reports whether the condition was met.

query_dataset accepts 1–1,000 rows and 1–30s. Model results have a 16 KiB limit.

Model queries first use a private snapshot of standard tables. Snapshots over 100,000 rows or 16 MiB fail explicitly.

get_overview

Read session state, cameras, destinations, storage and recording defaults. Works without a session.

Minimum risk class: observe. Session: not always necessary.

Arguments: {}.

list_cameras

List connected and discovered cameras. Set discover to true for a new search in a running session.

Minimum risk class: observe. Session: not always necessary.

list_destinations

Read destination names, folders and availability. Works without a session.

Minimum risk class: observe. Session: not always necessary.

Arguments: {}.

get_storage

Read the file budget, reservations and free space. Works without a session.

Minimum risk class: observe. Session: not always necessary.

Arguments: {}.

list_jobs

Read schedules, recordings and streams. A null camera lists all cameras.

Minimum risk class: observe. Session: necessary.

get_camera_features

Read imaging controls, limits and access. Set search or names to narrow the result.

Minimum risk class: observe. Session: necessary.

list_camera_setups

List the camera setups the user saved. A camera adds how each setup matches it. No tool saves or deletes a setup. Works without a session.

Minimum risk class: observe. Session: not always necessary.

preview_camera_setup

Compare a saved setup with a connected camera without changing it. Lists at most 40 changes and 20 values the camera cannot take; setup diff shows all.

Minimum risk class: observe. Session: necessary.

inspect_frame

Read a fresh camera image and exposure or focus measurements. A stopped camera acquires one frame and stays stopped. Document scanners are refused.

Minimum risk class: observe. Session: necessary.

wait_for

Wait for time, frames, stable auto exposure, job completion, recording stop or another participant’s action.

Minimum risk class: observe. Session: necessary.

get_dataset

Read dataset identity, standard tables, row counts, size, limits and errors without reading rows.

Minimum risk class: observe. Session: necessary.

Arguments: {}.

query_dataset

Run one read-only SELECT against the reviewed dataset. Model access to data must be allowed separately.

Minimum risk class: observe. Session: necessary.

open_dataset

Open or create a .duckdb catalog inside the capture folder. Existing databases are never overwritten.

Minimum risk class: bounded. Session: necessary.

close_dataset

Close the exact reviewed dataset instance. Approval is necessary because other work can use it.

Minimum risk class: disruptive. Session: necessary.

Arguments: {}.

annotate_dataset

Save a timestamped note of up to 4,096 bytes in the reviewed dataset.

Minimum risk class: bounded. Session: necessary.

export_dataset

Export selected data to a new analysis folder. Each attempt reserves twice the maximum bundle size.

Minimum risk class: bounded. Session: necessary.

connect_camera

Connect a source without starting live view. Size and fps arguments apply only to host webcams.

Minimum risk class: reversible. Session: necessary.

start_live_view

Start acquisition on a connected camera. For a scanner, this arms acquisition and asks for approval; an explicit capture requests a page.

Minimum risk class: reversible. Session: necessary.

stop_live_view

Stop acquisition. First stop recordings and streams, and cancel active capture schedules.

Minimum risk class: reversible. Session: necessary.

set_camera_features

Apply 1–16 feature values atomically. Optional expected values prevent overwriting a changed setting.

Minimum risk class: reversible. Session: necessary.

set_camera_roi

Set sensor offsets and dimensions within camera limits. Use full to restore the full sensor area.

Minimum risk class: reversible. Session: necessary.

set_auto_exposure

Select auto, hold or revert. A balance from 0 to 1 favors quality or frame rate.

Minimum risk class: reversible. Session: necessary.

run_camera_command

Run an allowed camera command, such as TriggerSoftware. Commands cannot be undone.

Minimum risk class: reversible. Session: necessary.

undo_camera_change

Undo the specified camera_change token. A null token uses this caller’s last change.

Minimum risk class: reversible. Session: necessary.

apply_camera_setup

Restore a saved setup as one camera change with one undo token. The step pins the setup's digest. Restores that may change values other than image quality are human_only.

Minimum risk class: reversible. Session: necessary.

capture_photos

Save 1–1,000 images; default 1. Default format is PNG. Scanners consume pages.

Minimum risk class: bounded. Session: necessary.

start_recording

Record video with a duration or a 512 MiB default reservation. Keep the session open and the computer awake.

Minimum risk class: bounded. Session: necessary.

stop_recording

Finish the current recording or stream. Stopping another participant’s work asks for approval.

Minimum risk class: bounded. Session: necessary.

schedule_captures

Save images at an interval. Set exactly one end condition: duration, count or until.

Minimum risk class: bounded. Session: necessary.

cancel_job

Cancel the specified schedule. Existing output stays saved. Cancelling another participant’s job asks for approval.

Minimum risk class: bounded. Session: necessary.

stream_to_url

Send video to RTSP, RTMP or SRT. Approval is always necessary. Supply passwords separately.

Minimum risk class: disruptive. Session: necessary.

create_folder_destination

Create a new named folder destination. Human approval is necessary.

Minimum risk class: human_only. Session: not always necessary.

RPC operations

Use structured JSON to control a running session.

Send a JSON object to capturefab --session NAME rpc through stdin. Set op to the operation below.

For HTTP, use POST /api/command with {version:1, camera:ID, command:{op:…}}.

Private local IPC uses an authentication token. The HTTP listener uses network access controls and has no separate login.

Use schema --json for runnable request examples, response fields and errors. Private IPC requests have a 1 MiB size limit.

printf '%s\n' '{"op":"frame","fresh":1,"max_dimension":1024}' | capturefab --session bench --camera sim:0 rpc --json

RPC frame format is auto, jpeg or png. Auto selects JPEG when supported, otherwise PNG.

RPC frame accepts fresh 0–10 and timeout_ms 1–10,000. The default timeout is 3,000 ms.

Its longest preview edge is 64–2,048 pixels, default 1,024. Use 0 for measurements only; encoded images have a 1.5 MiB limit.

Use normalized [x,y,width,height] for a region. A stopped camera acquires one frame and remains stopped; scanners are refused.