CLI Reference¶
Complete command-line interface documentation.
Reading the tables
In the Values column:
- Flag = No argument needed; presence enables the option (e.g.,
--tracking) INT/FLOAT= Numeric value (e.g.,--batch_size 8)PATH= File or directory path- Comma-separated values = Choose one (e.g.,
auto,cuda,cpu)
Commands¶
| Command | Description |
|---|---|
sleap-nn train |
Train models |
sleap-nn predict |
Run inference on videos/labels (checkpoints or exported models) — recommended |
sleap-nn track |
Run inference/tracking (legacy pipeline) |
sleap-nn eval |
Evaluate predictions |
sleap-nn eval-tracking |
Evaluate identity persistence of tracked predictions |
sleap-nn export |
Export to ONNX/TensorRT |
sleap-nn config |
Generate training configs (experimental) |
sleap-nn info |
Inspect trained models |
sleap-nn system |
System diagnostics |
sleap-nn train¶
Train pose estimation models.
Options¶
| Option | Short | Description |
|---|---|---|
--config |
Path to config YAML file | |
--config-dir |
-d |
Directory containing config file |
--config-name |
-c |
Config file name (without .yaml) |
--video-paths |
-v |
Replace video paths (multiple allowed) |
--video-path-map |
Map old path to new (OLD NEW) | |
--prefix-map |
Map path prefix (OLD_PREFIX NEW_PREFIX) | |
--labels |
-l |
Training labels .slp, replacing data_config.train_labels_path (multiple allowed) |
--val-labels |
Validation labels .slp, replacing data_config.val_labels_path (multiple allowed) |
|
--resume |
Resume a run from its folder or a .ckpt file (writes to a new <run_name>-1 folder) |
|
--dry-run |
Check the config and data (setup + one train/val batch on one batch of frames, with the config's settings), check the run can write to ckpt_dir (leaving nothing behind), print a summary |
Examples¶
# Simple
sleap-nn train --config config.yaml
# With directory/name
sleap-nn train -d /configs -c my_config
# Override values
sleap-nn train --config config.yaml trainer_config.max_epochs=200
# Train a config on a different labels file
sleap-nn train config.yaml --labels labels.slp
sleap-nn train config.yaml -l train.slp --val-labels val.slp
# Remap video paths
sleap-nn train --config config.yaml --prefix-map /old/data /new/data
# Check a config before a long run
sleap-nn train --config config.yaml --dry-run
# Resume a run (and train it longer)
sleap-nn train --resume models/my_run trainer_config.max_epochs=200
sleap-nn track¶
Run inference and/or tracking.
Legacy pipeline
sleap-nn track runs the older legacy inference pipeline. It is still
supported, but sleap-nn predict is the recommended
command — it accepts the same options and additionally runs exported
ONNX/TensorRT models. The options documented below also apply to predict.
Essential Options¶
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--data_path |
-i |
Video or labels file | PATH |
Required |
--model_paths |
-m |
Model dir, or its best.ckpt / training_config.yaml (multiple for top-down) |
PATH |
Required* |
--output_path |
-o |
Output file path | PATH |
<input>.predictions.slp |
--device |
-d |
Compute device | auto, cuda, cuda:0, cuda:1, cpu, mps |
auto |
--batch_size |
-b |
Batch size | INT |
4 |
--tracking |
-t |
Enable tracking | Flag | false |
*Not required for track-only mode.
Each --model_paths entry may be a model directory, or a path to that model's best.ckpt or training_config.yaml/.json file — all three resolve to the model directory and load best.ckpt. (A different checkpoint such as last.ckpt still loads best.ckpt and warns; use --backbone_ckpt_path / --head_ckpt_path for a specific checkpoint.)
Output Options¶
| Option | Description | Values | Default |
|---|---|---|---|
--gui |
Output JSON progress for GUI integration | Flag | false |
Data Selection¶
| Option | Description | Values | Default |
|---|---|---|---|
--frames |
Frame indices to process | 0-100, 0-100,200-300 |
All frames |
--video_index |
Video index in multi-video .slp | INT |
0 |
--only_labeled_frames |
Only process labeled frames | Flag | false |
--only_suggested_frames |
Only process suggested frames | Flag | false |
--exclude_user_labeled |
Skip user-labeled frames | Flag | false |
--only_predicted_frames |
Only process frames with predictions | Flag | false |
Filtering¶
| Option | Description | Values | Default |
|---|---|---|---|
--max_instances |
Max instances per frame (forward pass only) | INT |
None |
--filter_min_visible_nodes |
Min visible keypoints required | INT |
0 |
--filter_min_visible_node_fraction |
Min fraction of skeleton nodes visible | FLOAT (0.0-1.0) |
0.0 |
--filter_min_mean_node_score |
Min mean confidence across visible nodes | FLOAT (0.0-1.0) |
0.0 |
--filter_min_instance_score |
Min overall instance score | FLOAT (0.0-1.0) |
0.0 |
--filter_overlapping |
Remove duplicate instances (inference only) | Flag | false |
--filter_overlapping_method |
Overlap calculation method | iou, oks |
iou |
--filter_overlapping_threshold |
Similarity threshold for filtering | FLOAT (0.0-1.0) |
0.8 |
Processing order
When running inference + tracking: --max_instances (forward pass) → node count filter → confidence filter → overlap filter → tracking. In track-only mode, filtering is applied before tracking on existing predictions.
Tracking¶
| Option | Description | Values | Default |
|---|---|---|---|
These are the options of the default classic tracker. See the [tracking |
|||
| guide](../guides/tracking.md#tracking-parameters) for the full list. |
| Option | Description | Values | Default |
|---|---|---|---|
--tracking |
Enable tracking | Flag | false |
--tracking_window_size |
Frames to look back | INT |
5 |
--candidates_method |
Candidate selection method | fixed_window, local_queues |
fixed_window (local_queues for --features embeddings, mask tracking, or with --max_tracks) |
--max_tracks |
Maximum track count (auto-selects local_queues) |
INT |
None |
--features |
Features for matching. Unset: centroids for single-node skeletons, masks for segmentation-only output |
keypoints, centroids, bboxes, masks, embeddings |
keypoints |
--scoring_method |
Similarity scoring method. Unset: euclidean_dist for single-node skeletons, mask_iou for masks, cosine_sim for --features embeddings |
oks, cosine_sim, iou, mask_iou, euclidean_dist |
oks |
--oks_stddev |
OKS keypoint spread | FLOAT |
0.025 |
--use_flow |
Enable optical flow | Flag | false |
--use_kalman |
Enable Kalman-filter motion model (needs a target instance count) | Flag | false |
--appearance_weight |
predict only. Blend re-ID appearance into the geometric score (details) |
FLOAT in [0, 1] |
0.0 |
--euclidean_scale |
predict only. Pixel scale for blending appearance into euclidean_dist |
FLOAT |
None |
--link_tracklets |
predict only. Identity linking after tracking each video (details) |
Flag | false |
--max_tracks requires local_queues
With the classic tracker, --max_tracks is honored only by local_queues;
fixed_window ignores it. Setting it auto-selects candidates_method
local_queues (logged at INFO), so you do not need to set
--candidates_method yourself.
Modern MOT trackers (sleap-nn predict only)¶
--tracker selects one of the modern MOT
trackers. These options apply only to
those trackers. Unset options take the tracker's preset value (animal preset
shown). Giving a classic-only option to a MOT tracker, or a MOT-only option to
classic, is an error; the one exception is --mot_param time_base=... /
body_size=... with classic --link_tracklets, which its identity linking reads.
| Option | Description | Values | Default |
|---|---|---|---|
--tracker |
Tracking algorithm | classic, sort, deepsort, strongsort, bytetrack, botsort, ocsort, deepocsort |
classic |
--track_buffer |
Steps a lost track is kept for re-association | INT |
30 (paper preset: 1 for sort) |
--min_hits |
Matches before a track is confirmed (earlier detections then labeled) | INT |
3 (2 for bytetrack, botsort) |
--track_high_threshold |
Score above which a detection is high-confidence | FLOAT in [0, 1] |
per tracker |
--track_low_threshold |
Detections scoring at or below this are ignored | FLOAT in [0, 1] |
0.1 |
--new_track_threshold |
Minimum score to start a track | FLOAT in [0, 1] |
per tracker |
--min_match_similarity |
Minimum geometric similarity for a first-stage match | FLOAT in [0, 1] |
0.3 (0.2 for bytetrack, botsort) |
--appearance_threshold |
Appearance trackers (deepsort, strongsort, botsort, deepocsort): minimum cosine, or auto (calibrated per video) |
auto, FLOAT in [-1, 1] |
auto |
--link_tracklets |
Identity linking after tracking each video | Flag | false |
--max_tracks |
Known number of animals: closed-set identity linking, at most N tracks per video | INT |
None |
--mot_param |
Override any MOT parameter, e.g. preset=paper, score_mode=none, use_byte=true, normalize_scores=false (thresholds on raw scores instead of per-video normalized ones), body_size=40 (animal size in px, e.g. for centroid-only models) (repeatable). With classic: only time_base / body_size, with --link_tracklets |
KEY=VALUE |
— |
--scoring_method |
Geometric similarity | iou, oks, euclidean_dist (centroid) |
auto |
--oks_stddev |
OKS spread for --scoring_method oks (refused with any other similarity) |
FLOAT |
0.1 |
--features |
Carrier to track (one the labels do not hold is an error) | keypoints, masks |
auto |
Examples¶
# Basic inference
sleap-nn track -i video.mp4 -m models/bottomup/
# Top-down (two models)
sleap-nn track -i video.mp4 -m models/centroid/ -m models/instance/
# With tracking
sleap-nn track -i video.mp4 -m models/bottomup/ -t
# Track-only (no inference)
sleap-nn track -i labels.slp -t
# Filter overlapping + tracking
sleap-nn track -i video.mp4 -m models/ --filter_overlapping -t
# Modern MOT tracker (predict only): retrack existing predictions with ByteTrack
sleap-nn predict -i labels.slp -t --tracker bytetrack
sleap-nn predict¶
Run inference on videos or labels files. This is the canonical command for the unified inference pipeline, and runs on both trained checkpoint models and exported ONNX/TensorRT models.
sleap-nn predict accepts the same options as sleap-nn track (data selection, filtering, device, batch size, etc.). Add --tracking to enable tracking.
sleap-nn infer is deprecated
sleap-nn infer still works as a hidden alias for predict but emits a
DeprecationWarning. Use sleap-nn predict instead.
Running exported models¶
predict auto-detects exported models: if --model_paths/-m points to a directory containing model.onnx or model.trt, it runs the exported-model runtime instead of loading a trained checkpoint. Use --runtime to choose the runtime.
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--runtime |
Exported-model runtime (ignored for checkpoints) | auto, onnx, tensorrt |
auto |
--runtime auto prefers TensorRT and falls back to ONNX.
Examples¶
# Trained checkpoint (top-down, two models)
sleap-nn predict -i video.mp4 -m models/centroid -m models/centered_instance -o predictions.slp
# Exported model directory (auto-detected) with TensorRT
sleap-nn predict -m exports/model -i video.mp4 --runtime tensorrt -o predictions.slp
sleap-nn eval¶
Evaluate predictions against ground truth.
Options¶
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--ground_truth_path |
-g |
Ground truth labels | PATH |
Required |
--predicted_path |
-p |
Predicted labels | PATH |
Required |
--save_metrics |
-s |
Save metrics to .npz | PATH |
None |
--oks_stddev |
OKS standard deviation | FLOAT |
0.025 |
|
--oks_scale |
Scale factor for OKS calculation | FLOAT |
None | |
--match_threshold |
Instance matching threshold | FLOAT |
0.0 |
|
--match_method |
Matcher: oks, centroid, mask, auto |
CHOICE |
auto |
|
--anchor_part |
GT node for centroid-mode GT centroids | STR |
None | |
--user_labels_only / --no-user_labels_only |
Only evaluate user-labeled | Flag | True |
|
--count_unmatched_as_fp / --no-count_unmatched_as_fp |
Count unmatched predictions as false positives in oks_voc.* |
Flag | off |
Example¶
sleap-nn eval-tracking¶
Score whether tracks keep the right identity, against tracked ground truth. It
reports sleap-nn's identity metrics (ID switches, IDF1, MT/PT/ML, fragmentation,
purity, coverage). It also reports TrackEval-faithful CLEAR-MOT, IDF1 and HOTA,
saved under the "mot" key. See Evaluating Identity
Persistence.
Options¶
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--ground_truth_path |
-g |
Tracked ground-truth labels | PATH |
Required |
--predicted_path |
-p |
Tracked predicted labels | PATH |
Required |
--save_metrics |
-s |
Save metrics to .json | PATH |
None |
--carrier |
What carries identity | auto, pose, mask |
auto |
|
--match_threshold |
Minimum OKS / mask IoU to match; maximum centroid distance (px) for single-node skeletons | FLOAT |
0.5 (50 px) |
|
--mt_threshold / --ml_threshold |
Coverage cuts for mostly-tracked / mostly-lost (legacy identity block; the mot block keeps TrackEval's fixed 0.8 / 0.2) |
FLOAT |
0.8 / 0.2 |
|
--oks_stddev |
OKS keypoint spread used to match poses | FLOAT > 0, finite |
0.025 |
|
--user_labels_only / --no-user_labels_only |
Drop predicted detections from the ground-truth side | Flag | False |
|
--global_identity / --per_video_identity |
Score track names as identities shared across videos | Flag | per video |
Example¶
sleap-nn export¶
Export models to ONNX/TensorRT.
Options¶
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--output-dir |
-o |
Output directory | PATH |
Required |
--format |
-f |
Export format | onnx, tensorrt, both |
onnx |
--precision |
TensorRT precision | fp32, fp16 |
fp16 |
|
--max-instances |
-n |
Max instances per frame | INT |
20 |
--max-batch-size |
-b |
Max batch size | INT |
8 |
Examples¶
# ONNX only
sleap-nn export models/bottomup -o exports/ --format onnx
# Both formats
sleap-nn export models/bottomup -o exports/ --format both
# Top-down (two models)
sleap-nn export models/centroid models/instance -o exports/
Running exported models
Inference on exported ONNX/TensorRT models is handled by sleap-nn predict — pass the export directory via -m and pick the runtime with --runtime. See sleap-nn predict above.
sleap-nn config¶
Experimental
This feature is experimental and may change in future releases.
Generate training configuration files interactively or automatically.
Options¶
| Option | Short | Description | Values | Default |
|---|---|---|---|---|
--output |
-o |
Output path for config file(s) | PATH |
<slp_name>_config.yaml |
--auto |
Auto-generate without interactive TUI | Flag | false |
|
--pipeline |
Model pipeline type | single_instance, bottomup, topdown, multi_class_bottomup, multi_class_topdown, centroid, bbox_centernet, bbox_ssd, topdown_bbox_centernet, topdown_bbox_ssd |
Auto-detected | |
--show-yaml |
Print YAML to stdout instead of saving | Flag | false |
Modes¶
Interactive TUI¶
Launch an interactive terminal UI to configure training:
Auto Mode¶
Generate a config with smart defaults based on your data:
Examples¶
# Interactive configuration
sleap-nn config labels.slp
# Auto-generate with defaults
sleap-nn config labels.slp --auto
# Auto-generate with custom output
sleap-nn config labels.slp --auto -o my_config.yaml
# Auto-generate with overrides
sleap-nn config labels.slp --auto --pipeline bottomup
# Preview YAML without saving
sleap-nn config labels.slp --auto --show-yaml
Output¶
For top-down pipelines, two config files are generated:
<name>_centroid.yaml- Centroid model config<name>_centered_instance.yaml- Centered instance model config
The box-detector top-down pipelines (topdown_bbox_centernet / topdown_bbox_ssd)
write <name>_bbox_centernet.yaml (or <name>_bbox_ssd.yaml) and a
<name>_centered_instance.yaml with box-scaled crops.
For other pipelines, a single config file is generated.
See the Config Generator Guide for detailed usage.
sleap-nn info¶
Inspect a trained model directory or training config file. Shows model architecture, data settings, training configuration, training results, evaluation metrics, and files.
PATH can be either:
- A trained model directory — shows full summary including training results, evaluation metrics, and files
- A training config YAML file — shows config summary only
Output Sections¶
| Section | Shown when |
|---|---|
| Model Info | Always — model type, backbone, head, parameters, skeleton |
| Data | Always — training/val data paths, preprocessing, augmentations |
| Training | Always — optimizer, epochs, batch size, LR scheduler, early stopping |
| Training Results | Model directory with training_log.csv — epochs trained, losses |
| Evaluation Metrics | Model directory with metrics .npz files — mOKS, mAP, distances, PCK |
| Files | Model directory — file listing with sizes |
Examples¶
# Inspect a trained model
sleap-nn info models/my_training_run/
# View config only
sleap-nn info training_config.yaml
sleap-nn system¶
Display system information and GPU diagnostics.
Shows: - Python version - PyTorch version and build - CUDA/cuDNN versions - GPU details (name, memory, compute capability) - Driver compatibility - Installed package versions
Environment Variables¶
| Variable | Description |
|---|---|
CUDA_VISIBLE_DEVICES |
Control visible GPUs |
WANDB_API_KEY |
WandB API key |