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 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.

sleap-nn train --config CONFIG_PATH [OPTIONS] [OVERRIDES]

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)

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

# Remap video paths
sleap-nn train --config config.yaml --prefix-map /old/data /new/data

---

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.

sleap-nn track --data_path INPUT --model_paths MODEL [OPTIONS]

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
--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
--max_tracks	Maximum track count (auto-selects local_queues)	INT	None
--features	Features for matching	keypoints, centroids, bboxes, image	keypoints
--scoring_method	Similarity scoring method	oks, cosine_sim, iou, euclidean_dist	oks
--use_flow	Enable optical flow	Flag	false

--max_tracks requires local_queues

--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.

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

---

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 --data_path INPUT --model_paths MODEL [OPTIONS]

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.

sleap-nn eval --ground_truth_path GT --predicted_path PRED [OPTIONS]

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

Example

sleap-nn eval -g ground_truth.slp -p predictions.slp -s metrics.npz

---

sleap-nn export

Export models to ONNX/TensorRT.

sleap-nn export MODEL_PATH [MODEL_PATH_2] -o OUTPUT_DIR [OPTIONS]

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.

sleap-nn config SLP_PATH [OPTIONS]

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	Auto-detected
--show-yaml		Print YAML to stdout instead of saving	Flag	false

Modes

Interactive TUI

Launch an interactive terminal UI to configure training:

sleap-nn config labels.slp

Auto Mode

Generate a config with smart defaults based on your data:

sleap-nn config labels.slp --auto -o config.yaml

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

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.

sleap-nn info PATH

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.

sleap-nn system

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

---

Global Options

sleap-nn --version  # Show version
sleap-nn --help     # Show help