CLI

Every candding command line subcommand and flag, from listing the registry to embedding text and benchmarking throughput.

The workspace ships a development binary called candding next to the library. It is the fastest way to look at the registry, pull weights, print a vector or measure throughput, and it is what the reference generator and the docs table call under the hood. In a checkout every invocation is cargo run -q -p candding-cli -- <command>; the examples below use the bare binary name for readability.

list-models

candding list-models
candding list-models --phase 0
candding list-models --json

Without a flag it prints one aligned row per registry model with the columns model, dim, pooling, max_len, phase and license. --phase keeps only the models of that phase. --json prints the full descriptor array instead, including the backends object with the per-device verification status, which is the same data the catalog table and the README table are generated from.

describe

candding describe BAAI/bge-small-en-v1.5
candding describe BAAI/bge-small-en-v1.5 --json

The plain form prints one field per line: id, family, dim, pooling, normalize, max length, the query and passage templates, license, size in gigabytes, phase and the three backend statuses. --json prints the descriptor as JSON, which is exactly what just golden hands to the reference generator so that Python and Rust agree on the templates and the length limit. A model that is not in the registry is an error that tells you to run candding list-models.

fetch

candding fetch BAAI/bge-small-en-v1.5
candding fetch phase:0
candding fetch BAAI/bge-small-en-v1.5 --revision refs/pr/1

fetch runs hf download with candding's include patterns, so it pulls the JSON files, the safetensors weights and the sentence-transformers directories, and skips ONNX, PyTorch, GGUF and OpenVINO exports. A target of phase:<n> expands to every registry model in that phase, and it prints a fetching <id> line before each download. --revision takes a branch, a tag or a commit hash and is passed straight through. When the hf binary is missing, the error names the install command and the exact download command to run by hand.

embed

cargo run -q -p candding-cli -- embed BAAI/bge-small-en-v1.5 "hello world" --query --json

Every text after the model id is embedded, and the vectors are printed one line per input with six decimals per value, or as a JSON array of arrays with --json.

Flag	Effect
`--query`	applies the model's query template; mutually exclusive with `--passage`
`--passage`	applies the model's passage template
`--dim <n>`	Matryoshka truncation to `n` columns, for models whose descriptor allows it
`--count`	prints the token count and the text per line instead of the vectors
`--device auto\|cpu\|metal\|cuda`	the device, `auto` by default
`--dtype f32\|f16\|bf16`	the weight dtype, `f32` by default
`--max-length <n>`	overrides the descriptor default, capped at the model's position limit
`--json`	one JSON array of arrays instead of the plain lines

--count is the quickest tokenizer check there is: it reports the tokens the model will see after truncation, special tokens included and templates excluded, which is the number a golden mismatch is usually traced back to. --dim on a model without Matryoshka support fails before anything is tokenized, and no catalog model declares that support yet.

bench

cargo run --release -p candding-cli -- bench BAAI/bge-small-en-v1.5 --docs 256 --batch-sizes 1,8,32

bench builds synthetic documents whose lengths cycle between 8 and 200 words, runs a short warm-up, and then embeds the whole set once per batch size. It prints a header line with the model, the resolved device and the document count, then one line per batch size with the throughput in documents per second and the total wall time. --docs defaults to 256, --batch-sizes to 1,8,32, and --device and --dtype work as they do for embed.

Always benchmark a release build. cargo run --release -p candding-cli -- bench … is tens of times faster than the debug build, because the debug profile optimizes the dependencies but not the crate itself, so numbers from cargo run without --release say nothing about the library.

Backends and features

The CLI inherits the library's backend features, so --device metal only exists in a build that has the Metal backend compiled in.

cargo run -p candding-cli --features metal -- embed BAAI/bge-small-en-v1.5 "hello world" --device metal
cargo run -p candding-cli --features cuda -- embed BAAI/bge-small-en-v1.5 "hello world" --device cuda

Without the matching feature the device cannot be created and the command fails with a device error rather than falling back to CPU; --device auto is the flag that does fall back, and it picks Metal, then CUDA, then CPU as described on the devices and dtypes page.