Command Line Reference¶
SLEAP provides a unified command-line interface through the sleap command, with subcommands for different tasks.
Run sleap --help to see all available commands, or sleap <command> --help for details on a specific command.
Quick Reference¶
GUI & Diagnostics
| Command | Description |
|---|---|
sleap |
Launch the GUI (same as sleap label) |
sleap label |
Launch the SLEAP labeling GUI |
sleap doctor |
Show system diagnostics for troubleshooting |
Neural Network (requires sleap[nn])
| Command | Description |
|---|---|
sleap train |
Train pose estimation models |
sleap predict |
Run inference and tracking (recommended; also supports ONNX/TensorRT-exported models) |
sleap track |
Run inference and tracking (legacy pipeline; use sleap predict instead) |
sleap eval |
Evaluate predictions against ground truth |
sleap export-model |
Export model for deployment |
sleap system |
Show sleap-nn system information |
Data Commands (from sleap-io)
| Command | Description |
|---|---|
sleap convert |
Convert between pose data formats |
sleap export |
Export pose data for analysis (CSV, HDF5) |
sleap show |
Print labels file summary |
sleap render |
Render predictions as video or image |
sleap merge |
Merge multiple labels files |
sleap split |
Split labels into train/val/test sets |
sleap embed |
Embed video frames into labels file |
sleap unembed |
Remove embedded frames |
sleap filenames |
List or update video filenames |
sleap fix |
Fix common issues in labels files |
sleap trim |
Trim video and labels to frame range |
sleap reencode |
Reencode video for seekability |
sleap transform |
Transform video and adjust coordinates |
sleap unsplit |
Merge split files back into one |
GUI¶
sleap label¶
Launch the SLEAP labeling GUI. You can also just run sleap or sleap <file.slp>.
sleap label [OPTIONS] [LABELS.slp]
# Examples
sleap # Launch empty GUI
sleap label # Same as above
sleap my_project.slp # Open existing project
sleap label --reset # Reset GUI preferences
sleap --video-backend ffmpeg # Use imageio-ffmpeg for video
Options:
| Option | Description |
|---|---|
-v, --verbose |
Show detailed startup info including GPU status |
--reset |
Reset GUI preferences to defaults |
--no-usage-data |
Disable anonymous usage data collection |
--nonnative |
Use non-native file dialogs |
--video-backend |
Video backend plugin: opencv, FFMPEG, or pyav. Persists to preferences on use. |
Diagnostics¶
sleap doctor¶
Show system diagnostics for troubleshooting. Output is designed to be copy-pasted when reporting issues.
sleap doctor [OPTIONS]
# Examples
sleap doctor # Show diagnostics
sleap doctor --json # Output as JSON
sleap doctor -o report.txt # Save to file
Options:
| Option | Description |
|---|---|
--json |
Output as JSON for programmatic use |
-o, --output |
Save output to file |
Training & Inference¶
Training and inference are powered by sleap-nn, the PyTorch-based neural network package.
Note
These commands require sleap[nn] to be installed. They wrap the sleap-nn CLI.
sleap train¶
Train pose estimation models.
sleap train [OPTIONS] <config.yaml>
# Examples
sleap train config.yaml # Train with config file
sleap train --config configs/baseline.yaml
sleap predict¶
Run inference and tracking on videos. This is the recommended inference command — it
reproduces every model type sleap track supports, plus centroid-only and
segmentation-only models that sleap track doesn't, and can also run
ONNX/TensorRT-exported models via --runtime.
sleap predict [OPTIONS] -i <video> -m <model>
# Examples
sleap predict -i video.mp4 -m models/centroid/
sleap predict -i video.mp4 -m models/centroid/ -m models/instance/ --tracking
sleap track¶
Legacy command
sleap track runs sleap-nn's legacy inference pipeline and is kept for backwards
compatibility. Use sleap predict for new projects — it
supports everything sleap track does, plus more.
Run inference and tracking on videos using the legacy pipeline.
sleap track [OPTIONS] -i <video> -m <model>
# Examples
sleap track -i video.mp4 -m models/centroid/
sleap track -i video.mp4 -m models/centroid/ -m models/instance/ --tracking
Other Neural Network Commands¶
| Command | Description |
|---|---|
sleap eval |
Evaluate model predictions against ground truth |
sleap export-model |
Export model to ONNX for deployment |
sleap system |
Show sleap-nn system information |
Full sleap-nn CLI documentation
Data Commands¶
These commands are provided by sleap-io for working with labels files.
Full sleap-io CLI documentation
sleap convert¶
Convert between pose data formats.
sleap convert [OPTIONS] <input> -o <output>
# Examples
sleap convert labels.slp -o labels.nwb # SLP to NWB
sleap convert labels.slp -o labels.pkg.slp --embed user # Embed frames
sleap convert annotations.json -o labels.slp --from coco # COCO to SLP
Supported formats:
- Input: slp, nwb, coco, labelstudio, alphatracker, jabs, dlc, ultralytics, leap
- Output: slp, nwb, coco, labelstudio, jabs, ultralytics, csv
sleap export¶
Export pose data to analysis-ready formats (CSV, HDF5).
Unlike convert which transforms between label formats, export creates dense outputs optimized for analysis with full control over frame padding, video selection, and output structure.
sleap export [OPTIONS] <input> -o <output>
# Examples
sleap export predictions.slp -o analysis.csv # Export as CSV
sleap export predictions.slp -o analysis.h5 # Export as HDF5
sleap export labels.slp -o sparse.csv --no-empty-frames # Only frames with instances
sleap export multi.slp -o export.csv -v 0 # Export specific video
sleap export multi.slp -o export.csv -v all # Export all videos
sleap export large.slp -o data.csv --chunk-size 10000 # Memory-efficient
Key options:
| Option | Description |
|---|---|
-o, --output |
Output file path (required) |
--format csv\|h5 |
Output format (inferred from extension if not specified) |
--csv-format |
CSV layout: sleap, dlc, points, instances, frames (default) |
--h5-dim-order |
HDF5 axis ordering: matlab (SLEAP-compatible) or standard |
-v, --video |
Video index (0, 1, ...) or all for multi-video files |
--start, --end |
Frame range (inclusive start, exclusive end) |
--no-empty-frames |
Only include frames with instances (sparse output) |
--chunk-size |
Write CSV in chunks for large files |
sleap show¶
Print a summary of a labels file.
sleap render¶
Render pose predictions as video or image.
sleap render [OPTIONS] <labels.slp> -o <output.mp4>
# Examples
sleap render predictions.slp -o video.mp4
sleap render predictions.slp -o frame.png --frames 100
sleap merge¶
Merge multiple labels files into one.
sleap split¶
Split labels into train/validation/test sets.
Other Data Commands¶
| Command | Description |
|---|---|
sleap embed |
Embed video frames into a labels file |
sleap unembed |
Remove embedded frames, restore video references |
sleap filenames |
List or update video filenames |
sleap fix |
Fix common issues in labels files |
sleap trim |
Trim video and labels to a frame range |
sleap transform |
Transform video and adjust coordinates |
sleap reencode |
Reencode video for improved seekability |
sleap unsplit |
Merge split files back into one |
Legacy CLI¶
The following commands are provided for backwards compatibility. For new projects, use the unified sleap commands above.
sleap-label
Legacy entry point for the GUI. Use sleap label instead.
usage: sleap-label [-h] [--nonnative] [--profiling] [--reset] [labels_path]
positional arguments:
labels_path Path to labels file
optional arguments:
-h, --help show this help message and exit
--nonnative Don't use native file dialogs
--profiling Enable performance profiling
--reset Reset GUI state and preferences
sleap-train
Legacy training command. Use sleap train for new projects.
usage: sleap-train [-h] [--video-paths VIDEO_PATHS] [--val_labels VAL_LABELS]
[--test_labels TEST_LABELS] [--save_viz] [--keep_viz] [--zmq]
[--run_name RUN_NAME] [--prefix PREFIX] [--suffix SUFFIX]
[--cpu] [--first-gpu] [--last-gpu] [--gpu GPU]
training_job_path [labels_path]
positional arguments:
training_job_path Path to training job profile JSON/YAML file
labels_path Path to labels file for training
optional arguments:
--video-paths List of paths for finding videos
--val_labels, --val Path to validation labels file
--test_labels, --test Path to test labels file
--base_checkpoint Path to checkpoint to resume from
--save_viz Save prediction visualizations
--keep_viz Keep visualization images after training
--zmq Enable ZMQ logging (for GUI)
--run_name Run name for saving files
--prefix Prefix to prepend to run name
--suffix Suffix to append to run name
--cpu Run on CPU only
--first-gpu Run on first GPU
--last-gpu Run on last GPU
--gpu GPU Run on specific GPU (or 'auto')
sleap-track
Legacy inference command. Use sleap predict for new projects.
usage: sleap-track [-h] [-m MODELS] [--frames FRAMES] [-o OUTPUT] [--batch_size BATCH_SIZE]
[--peak_threshold PEAK_THRESHOLD] [-n MAX_INSTANCES]
[--tracking.tracker TRACKER] [--tracking.max_tracks MAX_TRACKS]
[--cpu | --first-gpu | --last-gpu | --gpu GPU]
[data_path]
positional arguments:
data_path Path to video, .slp file, or folder of videos
optional arguments:
-m, --model Path to trained model directory (can specify multiple)
--frames Frames to predict (e.g., "1,2,3" or "1-100")
--only-labeled-frames Only predict on labeled frames
--only-suggested-frames Only predict on suggested frames
-o, --output Output filename (default: [data_path].predictions.slp)
--no-empty-frames Clear empty frames before saving
--batch_size Frames per batch (default: 4)
--peak_threshold Minimum confidence threshold
-n, --max_instances Limit instances per frame
--open-in-gui Open results in GUI when done
Tracking options:
--tracking.tracker Tracker type: simple, flow, simplemaxtracks, flowmaxtracks
--tracking.max_tracks Maximum number of tracks
--tracking.track_window Frames to look back for matches (default: 5)
--tracking.similarity Similarity metric: instance, centroid, iou
--tracking.match Matching algorithm: hungarian, greedy
GPU options:
--cpu Run on CPU only
--first-gpu Run on first GPU
--last-gpu Run on last GPU
--gpu GPU Run on specific GPU (or 'auto')
Examples:
# Simple inference
sleap-track -m "models/my_model" -o "predictions.slp" "video.mp4"
# Multi-model pipeline (top-down)
sleap-track -m "models/centroid" -m "models/instance" -o "predictions.slp" "video.mp4"
# With tracking
sleap-track -m "models/my_model" --tracking.tracker simple -o "predictions.slp" "video.mp4"
# Re-track existing predictions
sleap-track --tracking.tracker simple -o "retracked.slp" "predictions.slp"
sleap-convert (legacy)
Legacy conversion command. Use sleap convert instead.
usage: sleap-convert [-h] [-o OUTPUT] [--format FORMAT] [--video VIDEO] input_path
positional arguments:
input_path Path to input file
optional arguments:
-o, --output Path to output file
--format Output format: slp, analysis, analysis.nix, analysis.csv, h5, json
--video Path to video (if needed)
Example:
sleap-inspect
Legacy inspection command. For labels files, use sleap show instead. Model
directory inspection has no equivalent in the unified sleap CLI yet.
sleap-render (legacy)
Legacy render command. Use sleap render instead.
usage: sleap-render [-h] [-o OUTPUT] [-f FPS] [--scale SCALE] [--frames FRAMES]
[--video-index VIDEO_INDEX] [--palette PALETTE] data_path
positional arguments:
data_path Path to labels file
optional arguments:
-o, --output Output path
--video-index Video index in labels (default: 0)
--frames Frames to render (e.g., "1,2,3" or "1-100")
-f, --fps Output FPS (default: 25)
--scale Image scale (default: 1.0)
--show_edges Draw lines between nodes (default: 1)
--marker_size Marker size in pixels (default: 4)
--palette Color palette: alphabet, five+, solarized, standard
--distinctly_color Color by: instances, edges, nodes
sleap-diagnostic
Legacy diagnostics command. Use sleap doctor instead. Note that sleap
doctor does not include a full pip freeze/conda list dump or the
--gui-check Qt smoke test; use sleap-diagnostic if you need those.
Note
For help with any command, run with --help (e.g., sleap convert --help).