Browse command reference
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.
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.
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.
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.
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.
List, examine and run shared image and data tools for people and external agents.
List shared image and data tools, risks and portable argument schemas.
Read one tool's description and argument schema without a session.
Read session facts or examine and run one image or data tool.
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 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.
Read session state, cameras, destinations, storage and recording defaults. Works without a session.
Minimum risk class: observe. Session: not always necessary.
Arguments: {}.
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.
Read destination names, folders and availability. Works without a session.
Minimum risk class: observe. Session: not always necessary.
Arguments: {}.
Read the file budget, reservations and free space. Works without a session.
Minimum risk class: observe. Session: not always necessary.
Arguments: {}.
Read schedules, recordings and streams. A null camera lists all cameras.
Minimum risk class: observe. Session: necessary.
Read imaging controls, limits and access. Set search or names to narrow the result.
Minimum risk class: observe. Session: necessary.
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 time, frames, stable auto exposure, job completion, recording stop or another participant’s action.
Minimum risk class: observe. Session: necessary.
Read dataset identity, standard tables, row counts, size, limits and errors without reading rows.
Minimum risk class: observe. Session: necessary.
Arguments: {}.
Run one read-only SELECT against the reviewed dataset. Model access to data must be allowed separately.
Minimum risk class: observe. Session: necessary.
Open or create a .duckdb catalog inside the capture folder. Existing databases are never overwritten.
Minimum risk class: bounded. Session: necessary.
Close the exact reviewed dataset instance. Approval is necessary because other work can use it.
Minimum risk class: disruptive. Session: necessary.
Arguments: {}.
Save a timestamped note of up to 4,096 bytes in the reviewed dataset.
Minimum risk class: bounded. Session: necessary.
Export selected data to a new analysis folder. Each attempt reserves twice the maximum bundle size.
Minimum risk class: bounded. Session: necessary.
Connect a source without starting live view. Size and fps arguments apply only to host webcams.
Minimum risk class: reversible. Session: necessary.
Start acquisition on a connected camera. For a scanner, this arms acquisition; an explicit capture requests a page. The tool asks for approval.
Minimum risk class: reversible. Session: necessary.
Stop acquisition. First stop recordings and streams, and cancel active capture schedules.
Minimum risk class: reversible. Session: necessary.
Apply 1–16 feature values atomically. Optional expected values prevent overwriting a changed setting.
Minimum risk class: reversible. Session: necessary.
Set sensor offsets and dimensions within camera limits. Use full to restore the full sensor area.
Minimum risk class: reversible. Session: necessary.
Select auto, hold or revert. A balance from 0 to 1 favors quality or frame rate.
Minimum risk class: reversible. Session: necessary.
Run an allowed camera command, such as TriggerSoftware. Commands cannot be undone.
Minimum risk class: reversible. Session: necessary.
Undo the specified camera_change token. A null token uses this caller’s last change.
Minimum risk class: reversible. Session: necessary.
Save 1–1,000 images; default 1. Default format is PNG. Scanners consume pages.
Minimum risk class: bounded. Session: necessary.
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.
Finish the current recording or stream. Stopping another participant’s work asks for approval.
Minimum risk class: bounded. Session: necessary.
Save images at an interval. Set exactly one end condition: duration, count or until.
Minimum risk class: bounded. Session: necessary.
Cancel the specified schedule. Existing output stays saved. Cancelling another participant’s job asks for approval.
Minimum risk class: bounded. Session: necessary.
Send video to RTSP, RTMP or SRT. Approval is always necessary. Supply passwords separately.
Minimum risk class: disruptive. Session: necessary.
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.
Capturefab