biopb CLI¶
The biopb console script, generated from its actual Typer command tree --
including the tensor and image subcommand groups
(biopb.tensor.cli/biopb.image.cli), which are lazily-imported sub-apps of
biopb.cli:app and so render here too.
biopb¶
BioPB: open protobuf/gRPC protocols for biomedical image processing
Usage¶
biopb [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--install-completion |
Install completion for the current shell. | No | - |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. | No | - |
Commands¶
| Name | Description |
|---|---|
version |
Show the product deployment and biopb SDK... |
dashboard |
Open the biopb dashboard, starting the... |
skip-windows-defender |
Speed up biopb startup on Windows with a... |
uninstall |
Remove biopb: stop services, unregister... |
tensor |
Query a TensorFlight data plane (sources,... |
image |
Call algorithm servers (Ops). |
mcp |
Run a foreground napari viewer session... |
control |
Manage the control plane, which supervises... |
agents |
Register biopb-mcp with local AI agent... |
Subcommands¶
version¶
Show the product deployment and biopb SDK versions.
Usage¶
biopb version [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
dashboard¶
Open the biopb dashboard, starting the control plane if needed.
Usage¶
biopb dashboard [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--base-port INTEGER |
Base port for the whole deployment. The three listeners are derived from it: control/browser UI = base+3, tensor HTTP sidecar = base+4, flight gRPC = base+5 (so the 8810 default gives 8813/8814/8815). Same convention as the container's BIOPB_BASE_PORT. Move it to run a second deployment alongside another user's — give that one its own BIOPB_STATE_HOME too. | No | 8810 |
--grpc-bind TEXT |
Address the flight (data-plane) server binds. Loopback (the default, 127.0.0.1) keeps the deployment on this machine. A public address (0.0.0.0, or one interface's IP) serves it to other machines, and then an access token is REQUIRED — supplied via --token, else generated and printed — and TLS is on by default. This is the only listener that is ever published: the sidecar and the browser UI stay on loopback, reachable off-box through the ssh -L tunnel printed on start. | No | - |
--grpc-external-location TEXT |
The address a remote client should dial to reach the data plane, advertised via its health action (biopb/biopb#1158) -- e.g. 'grpc://hostname:8815', or a scheduler-assigned FQDN on an HPC job. Required when --grpc-bind is a public address: nothing here can guess a reachable address for a wildcard bind. Pure passthrough -- the data plane is the single place this is validated and enforced. |
No | - |
--no-browser |
Ensure the control plane is up but only print the dashboard URL instead of opening a browser. | No | False |
--remote |
Deprecated alias for --grpc-bind 0.0.0.0. | No | False |
skip-windows-defender¶
Speed up biopb startup on Windows with a Defender exclusion.
Usage¶
biopb skip-windows-defender [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--enable / --disable |
Enable (add) or disable (remove) the Defender exclusion; omit to show the current status. | No | - |
uninstall¶
Remove biopb: stop services, unregister from agents, delete the install.
Usage¶
biopb uninstall [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--purge |
Also delete biopb's config and cached/state data. Your image data is never touched. | No | False |
-y, --yes |
Don't ask for confirmation. | No | False |
tensor¶
Query a TensorFlight data plane (sources, tensors, stats, cache).
Usage¶
biopb tensor [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
query¶
List the data sources and tensors a server is serving.
Usage¶
biopb tensor query [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--cache-bytes INTEGER |
Maximum bytes for the client-side chunk cache | No | 100000000 |
prune-annotations¶
Report, and optionally delete, ROI annotations whose image is gone.
Usage¶
biopb tensor prune-annotations [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--days INTEGER |
Delete annotations unseen for this many days. | Yes | - |
--apply |
Actually delete. Without it this only reports. | No | False |
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--cache-bytes INTEGER |
Maximum bytes for the client-side chunk cache | No | 100000000 |
metadata¶
Inspect a source's metadata and its tensor descriptors.
Usage¶
biopb tensor metadata [OPTIONS] SOURCE_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
SOURCE_ID |
Source identifier to inspect | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
--tensor TEXT |
Specific tensor ID to inspect (optional) | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--cache-bytes INTEGER |
Maximum bytes for the client-side chunk cache | No | 100000000 |
get¶
Download a tensor to a file or stdout (pickle, zarr, or protobuf).
Usage¶
biopb tensor get [OPTIONS] ARRAY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
ARRAY_ID |
Array identifier: source_id/tensor_id (tensor_id optional for single-tensor sources) | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-o, --output TEXT |
Output path. Use '-' for stdout. Format inferred from extension: .pkl (pickle), .zarr (zarr), .pb (protobuf) | No | - |
-f, --format TEXT |
Output format: pickle (lazy dask), zarr (realized), pb (protobuf). Inferred from filename if not set. | No | - |
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-S, --slice TEXT |
Slice specification, e.g. '0:100,0:200' | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--cache-bytes INTEGER |
Maximum bytes for the client-side chunk cache | No | 100000000 |
stats¶
Compute a tensor's min, max and mean (optionally over a slice).
Usage¶
biopb tensor stats [OPTIONS] ARRAY_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
ARRAY_ID |
Array identifier: source_id/tensor_id (tensor_id optional for single-tensor sources) | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-S, --slice TEXT |
Slice specification, e.g. '0:100,0:200' | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--cache-bytes INTEGER |
Maximum bytes for the client-side chunk cache | No | 100000000 |
cache-stats¶
Show the server's chunk-cache hit/miss diagnostics.
Usage¶
biopb tensor cache-stats [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--json |
Emit machine-readable JSON instead of a table | No | False |
decode-rates¶
Show measured decode throughput (MB/s) per tensor.
Usage¶
biopb tensor decode-rates [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
TensorFlight server URI. Default: $BIOPB_TENSOR_URL, else the endpoint the control plane publishes, else the local default. | No | - |
-t, --token TEXT |
Bearer token. Default: $BIOPB_TENSOR_TOKEN, else -- for the endpoint the control plane published -- the credential file it writes. An endpoint given with --server or $BIOPB_TENSOR_URL is never dialed with that file. | No | - |
--json |
Emit machine-readable JSON instead of a table | No | False |
image¶
Call algorithm servers (Ops).
Usage¶
biopb image [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
servers¶
List the configured algorithm servers with a health probe.
Usage¶
biopb image servers [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--json |
Emit machine-readable JSON instead of a table | No | False |
--timeout FLOAT |
Per-server probe deadline in seconds | No | 4.0 |
ops¶
List the operations an algorithm server offers.
Usage¶
biopb image ops [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-s, --server TEXT |
Algorithm server URI (grpc:// or grpcs://) | No | grpc://localhost:50051 |
-t, --token TEXT |
Bearer token for server authentication | No | - |
process¶
Run an operation on an algorithm server.
Usage¶
biopb image process [OPTIONS][INPUT]
Arguments¶
| Name | Description | Required |
|---|---|---|
INPUT |
Input file path or '-' for stdin. If omitted, reads from stdin. | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-o, --op TEXT |
Operation name (optional if the server has a single op) | No | - |
--tensor TEXT |
Which tensor argument the input is (optional if the op has one) | No | - |
-k, --kwargs TEXT |
The op's other arguments as a JSON object, e.g. '{"sigma": 2}' | No | - |
-O, --output TEXT |
Output path. Use '-' for stdout. Eager data requires filename. | No | - |
-f, --format TEXT |
Output format for lazy data: pb (default) or pickle. | No | - |
-s, --server TEXT |
Algorithm server URI (grpc:// or grpcs://) | No | grpc://localhost:50051 |
-t, --token TEXT |
Bearer token for server authentication | No | - |
mcp¶
Run a foreground napari viewer session (biopb-mcp).
Usage¶
biopb mcp [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
view¶
Open the napari viewer in this terminal (Ctrl-C to stop).
Usage¶
biopb mcp view [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-p, --port INTEGER |
MCP port for an optional agent to attach (default: dynamic, OS-assigned — printed on startup). | No | - |
control¶
Manage the control plane, which supervises the data plane.
Usage¶
biopb control [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
start¶
Start the control plane (and its data plane) as a daemon.
Usage¶
biopb control start [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-c, --config PATH |
Tensor-server config (biopb.json) | No | /home/runner/.config/biopb/biopb.json |
--static-dir PATH |
Web UI bundle the control serves at its root (the built web/ dist) | No | /home/runner/.local/share/biopb/webapp |
--base-port INTEGER |
Base port for the whole deployment. The three listeners are derived from it: control/browser UI = base+3, tensor HTTP sidecar = base+4, flight gRPC = base+5 (so the 8810 default gives 8813/8814/8815). Same convention as the container's BIOPB_BASE_PORT. Move it to run a second deployment alongside another user's — give that one its own BIOPB_STATE_HOME too. | No | 8810 |
-l, --log-level TEXT |
Control log level | No | INFO |
--grpc-bind TEXT |
Address the flight (data-plane) server binds. Loopback (the default, 127.0.0.1) keeps the deployment on this machine. A public address (0.0.0.0, or one interface's IP) serves it to other machines, and then an access token is REQUIRED — supplied via --token, else generated and printed — and TLS is on by default. This is the only listener that is ever published: the sidecar and the browser UI stay on loopback, reachable off-box through the ssh -L tunnel printed on start. | No | - |
--tls / --no-tls |
Serve the flight port over TLS with a self-signed certificate (generated on first use); clients dial grpcs:// and pin it on first connect. Defaults to ON for a public --grpc-bind and off for loopback, so the default follows the exposure. --tls needs the 'tls' extra; read the fingerprint with biopb-tensor-server cert init. --no-tls on a public bind sends the token in cleartext — trusted networks only. |
No | - |
--tls-cert PATH |
PEM certificate chain the data plane serves, instead of the self-signed one it mints into the state tree. Implies --tls, and needs no 'cryptography' extra. Use it to serve one long-lived certificate that outlives a single launch — one cert shared by every node a scheduler might pick — so clients pin once instead of per launch. It must carry a loopback SAN (localhost / 127.0.0.1) besides the names clients dial, or the co-located sidecar cannot reach the flight plane; and a client on this machine reads its anchor from the state tree, so put a copy of the cert (not the key) there too. Requires --tls-key. | No | - |
--tls-key PATH |
PEM private key paired with --tls-cert. | No | - |
--san TEXT |
Extra hostname or IP to put in the certificate the data plane mints (repeatable). Needed when clients dial a name this host cannot discover itself — a NAT/VPN address, a CNAME, the scheduler's name for this node — because gRPC verifies the dialed name against the SANs even though trust comes from the client's pin. Applies only when the cert is generated: it is ignored once one exists (re-mint with biopb-tensor-server cert init --force --san ...) and by --tls-cert. |
No | - |
--token TEXT |
Access token (or set BIOPB_TENSOR_TOKEN). Enforced with either bind: required for a public --grpc-bind (auto-generated if omitted), optional on loopback as defense-in-depth on a shared machine. A loopback token gates the browser too; local clients read it from the credential file the control writes, so biopb-mcp needs no environment of its own (biopb/biopb#470). | No | - |
--data-plane / --no-data-plane |
Bring the data plane up on start (default). With --no-data-plane the control plane starts without it; a client brings it up on demand via the control API. | No | data-plane |
--url-prefix TEXT |
Path prefix a reverse proxy publishes the browser UI under, instead of the origin root — e.g. --url-prefix /node/$host/$port for an Open OnDemand interactive app, whose route passes the full path through and rewrites nothing. Requests under the prefix are stripped before routing and the SPA shell is rewritten to point back at it; unprefixed requests keep working. Explicit configuration only: the prefix is never read off a request header such as X-Forwarded-Prefix. | No | - |
--grpc-external-location TEXT |
The address a remote client should dial to reach the data plane, advertised via its health action (biopb/biopb#1158) -- e.g. 'grpc://hostname:8815', or a scheduler-assigned FQDN on an HPC job. Required when --grpc-bind is a public address: nothing here can guess a reachable address for a wildcard bind. Pure passthrough -- the data plane is the single place this is validated and enforced. |
No | - |
--remote |
Deprecated alias for --grpc-bind 0.0.0.0. | No | False |
stop¶
Stop the control plane and the data plane it owns.
Usage¶
biopb control stop [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-t, --timeout INTEGER |
Seconds to wait for graceful shutdown | No | 10 |
status¶
Show the control plane's status and the data plane it supervises.
Usage¶
biopb control status [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--json |
Emit machine-readable JSON instead of a table | No | False |
logs¶
Show the control plane's log, or the data plane's with --data-plane.
Usage¶
biopb control logs [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--data-plane |
Show the supervised tensor server's log instead of the control's own | No | False |
-f, --follow |
Stream new log lines as they are written | No | False |
-n, --lines INTEGER |
Number of lines from the end to show (0 = all) | No | 200 |
--level TEXT |
Minimum level to show: DEBUG, INFO, WARNING, ERROR, CRITICAL | No | - |
--path |
Print the log file path and exit | No | False |
run¶
Removed -- use biopb control start, or biopb-control run for a true foreground process.
Usage¶
biopb control run [OPTIONS]
Arguments¶
No arguments available
Options¶
No options available
agents¶
Register biopb-mcp with local AI agent clients.
Usage¶
biopb agents [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
No options available
Subcommands¶
list¶
Show each supported client and whether biopb is registered.
Usage¶
biopb agents list [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--json |
Emit machine-readable JSON instead of a table | No | False |
register¶
Register biopb-mcp with a client (or all, with --all).
Usage¶
biopb agents register [OPTIONS][CLIENT]
Arguments¶
| Name | Description | Required |
|---|---|---|
CLIENT |
Client id (e.g. claude-code); omit when using --all | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--all |
Register with every detected client | No | False |
unregister¶
Remove biopb-mcp from a client (or all, with --all).
Usage¶
biopb agents unregister [OPTIONS][CLIENT]
Arguments¶
| Name | Description | Required |
|---|---|---|
CLIENT |
Client id (e.g. claude-code); omit when using --all | No |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--all |
Unregister from every currently registered client | No | False |