refactor(cli): Rename scripts→cli, integrate defopt

docs/index.md

@@ -41,11 +41,11 @@ Point at a video, webcam, RTSP stream, or image directory. Get tracked output.
 ```bash
 trackers track \
     --source video.mp4 \
-    --output output.mp4 \
-    --model rfdetr-medium \
+    --out.output output.mp4 \
+    --detection.model rfdetr-medium \
     --tracker bytetrack \
-    --show-labels \
-    --show-trajectories
+    --show.labels \
+    --show.trajectories
 ```
 
 For all CLI options, see the [tracking guide](learn/track.md).

docs/javascripts/command_builder.js

@@ -80,17 +80,17 @@ document.addEventListener("DOMContentLoaded", function () {
     }
 
     const prefix = state.modelType === "segmentation" ? "rfdetr-seg-" : "rfdetr-";
-    parts.push(`--model ${prefix}${state.modelSize}`);
+    parts.push(`--detection.model ${prefix}${state.modelSize}`);
 
     if (state.showModelOptions) {
       if (state.confidence !== defaults.confidence && isValidDecimal01(state.confidence, 0.05)) {
-        parts.push(`--model.confidence ${state.confidence}`);
+        parts.push(`--detection.confidence ${state.confidence}`);
       }
       if (state.device !== "auto") {
-        parts.push(`--model.device ${state.device}`);
+        parts.push(`--detection.device ${state.device}`);
       }
       if (state.classes && isValidClasses(state.classes)) {
-        parts.push(`--classes ${state.classes}`);
+        parts.push(`--filters.classes ${state.classes}`);
       }
     }
 
@@ -120,19 +120,19 @@ document.addEventListener("DOMContentLoaded", function () {
       }
     }
 
-    if (state.display) parts.push("--display");
-    if (!state.showBoxes) parts.push("--no-boxes");
-    if (state.showMasks) parts.push("--show-masks");
-    if (state.showConfidence) parts.push("--show-confidence");
-    if (state.showLabels) parts.push("--show-labels");
-    if (!state.showIds) parts.push("--no-ids");
-    if (state.showTrajectories) parts.push("--show-trajectories");
+    if (state.display) parts.push("--show.display");
+    if (!state.showBoxes) parts.push("--no-show-boxes");
+    if (state.showMasks) parts.push("--show.masks");
+    if (state.showConfidence) parts.push("--show.confidence");
+    if (state.showLabels) parts.push("--show.labels");
+    if (!state.showIds) parts.push("--no-show-ids");
+    if (state.showTrajectories) parts.push("--show.trajectories");
 
     const outputValue = state.output.trim();
     if (outputValue) {
-      parts.push(`--output ${outputValue}`);
+      parts.push(`--out.output ${outputValue}`);
       if (state.overwrite) {
-        parts.push("--overwrite");
+        parts.push("--out.overwrite");
       }
     }
 

docs/learn/detection-quality.md

@@ -66,10 +66,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     ```bash
     trackers track \
         --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
-        --model yolo26n-640 \
+        --detection.model yolo26n-640 \
         --tracker bytetrack \
-        --classes person \
-        --mot-output results/yolo26n/MOT17-13-FRCNN.txt
+        --filters.classes person \
+        --out.mot-results results/yolo26n/MOT17-13-FRCNN.txt
     ```
 
 === "All sequences"
@@ -78,10 +78,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
         trackers track \
             --source ./data/mot17/val/$seq/img1 \
-            --model yolo26n-640 \
+            --detection.model yolo26n-640 \
             --tracker bytetrack \
-            --classes person \
-            --mot-output results/yolo26n/$seq.txt
+            --filters.classes person \
+            --out.mot-results results/yolo26n/$seq.txt
     done
     ```
 
@@ -97,10 +97,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     ```bash
     trackers track \
         --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
-        --model rfdetr-nano \
+        --detection.model rfdetr-nano \
         --tracker bytetrack \
-        --classes person \
-        --mot-output results/rfdetr-nano/MOT17-13-FRCNN.txt
+        --filters.classes person \
+        --out.mot-results results/rfdetr-nano/MOT17-13-FRCNN.txt
     ```
 
 === "All sequences"
@@ -109,10 +109,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
         trackers track \
             --source ./data/mot17/val/$seq/img1 \
-            --model rfdetr-nano \
+            --detection.model rfdetr-nano \
             --tracker bytetrack \
-            --classes person \
-            --mot-output results/rfdetr-nano/$seq.txt
+            --filters.classes person \
+            --out.mot-results results/rfdetr-nano/$seq.txt
     done
     ```
 
@@ -128,10 +128,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     ```bash
     trackers track \
         --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
-        --model rfdetr-medium \
+        --detection.model rfdetr-medium \
         --tracker bytetrack \
-        --classes person \
-        --mot-output results/rfdetr-medium/MOT17-13-FRCNN.txt
+        --filters.classes person \
+        --out.mot-results results/rfdetr-medium/MOT17-13-FRCNN.txt
     ```
 
 === "All sequences"
@@ -140,10 +140,10 @@ Run ByteTrack with default parameters three times, changing only the detection m
     for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
         trackers track \
             --source ./data/mot17/val/$seq/img1 \
-            --model rfdetr-medium \
+            --detection.model rfdetr-medium \
             --tracker bytetrack \
-            --classes person \
-            --mot-output results/rfdetr-medium/$seq.txt
+            --filters.classes person \
+            --out.mot-results results/rfdetr-medium/$seq.txt
     done
     ```
 

docs/learn/evaluate.md

@@ -89,13 +89,13 @@ For more download options, see the [download guide](download.md).
 
 Feed the pre-computed detections into a tracker and write the results to a file for evaluation.
 
-Pass `--detections` to provide input detections and `--mot-output` to save the tracker output in MOT format.
+Pass `--detections` to provide input detections and `--out.mot-results` to save the tracker output in MOT format.
 
 ```text
 trackers track \
     --detections ./data/mot17/val/MOT17-02-FRCNN/det/det.txt \
     --tracker bytetrack \
-    --mot-output results/MOT17-02-FRCNN.txt
+    --out.mot-results results/MOT17-02-FRCNN.txt
 ```
 
 ---

docs/learn/track.md

@@ -49,7 +49,7 @@ Read frames from video files, webcams, RTSP streams, or image directories. Each
     Track objects with one command. Uses RF-DETR Nano and ByteTrack by default.
 
     ```text
-    trackers track --source source.mp4 --output output.mp4
+    trackers track --source source.mp4 --out.output output.mp4
     ```
 
 === "Python"
@@ -93,14 +93,14 @@ Trackers assign stable IDs to detections across frames, maintaining object ident
 
 === "CLI"
 
-    Select a tracker with `--tracker` and tune its behavior with `--tracker.*` arguments.
+    Select a tracker with `--tracker` and tune its behavior with per-parameter `--tracker.<name>` flags.
 
     ```text
     trackers track \
         --source source.mp4 \
         --tracker bytetrack \
-        --tracker.lost_track_buffer 60 \
-        --tracker.minimum_consecutive_frames 5
+        --tracker.lost-track-buffer 60 \
+        --tracker.minimum-consecutive-frames 5
     ```
 
 === "Python"
@@ -139,15 +139,15 @@ Trackers don't detect objects—they link detections across frames. A detection
 
 === "CLI"
 
-    Configure detection with `--model.*` arguments. Filter by confidence and class before tracking.
+    Configure detection with `--detection.*` arguments. Filter by confidence and class before tracking.
 
     ```text
     trackers track \
         --source source.mp4 \
-        --model rfdetr-medium \
-        --model.confidence 0.3 \
-        --model.device cuda \
-        --classes person,car
+        --detection.model rfdetr-medium \
+        --detection.confidence 0.3 \
+        --detection.device cuda \
+        --filters.classes person,car
     ```
 
 === "Python"
@@ -188,10 +188,10 @@ Visualization renders tracking results for debugging, demos, and qualitative eva
     ```text
     trackers track \
         --source source.mp4 \
-        --display \
-        --show-labels \
-        --show-confidence \
-        --show-trajectories
+        --show.display \
+        --show.labels \
+        --show.confidence \
+        --show.trajectories
     ```
 
 === "Python"
@@ -274,7 +274,7 @@ Save tracking results as annotated video files or display them in real time.
     Specify an output path to save annotated video.
 
     ```text
-    trackers track --source source.mp4 --output output.mp4 --overwrite
+    trackers track --source source.mp4 --out.output output.mp4 --out.overwrite
     ```
 
 === "Python"
@@ -342,97 +342,120 @@ All arguments accepted by the `trackers track` command.
       <td>—</td>
     </tr>
     <tr>
-      <td><code>--output</code></td>
+      <td><code>--out.output</code></td>
       <td>Path for output video. If a directory is given, saves as <code>output.mp4</code> inside it.</td>
       <td>none</td>
     </tr>
     <tr>
-      <td><code>--overwrite</code></td>
+      <td><code>--out.overwrite</code></td>
       <td>Allow overwriting existing output files. Without this flag, existing files cause an error.</td>
       <td><code>false</code></td>
     </tr>
     <tr>
-      <td><code>--model</code></td>
+      <td><code>--out.mot-results</code></td>
+      <td>Output path for tracker results in MOT format (per-frame detections with IDs).</td>
+      <td>none</td>
+    </tr>
+    <tr>
+      <td><code>--detections</code></td>
+      <td>Path to a pre-computed MOT-format detections file. When set, skips the detection model and feeds detections directly to the tracker. Mutually exclusive with <code>--detection.model</code>.</td>
+      <td>—</td>
+    </tr>
+    <tr>
+      <td><code>--detection.model</code></td>
       <td>Model identifier. Pretrained: <code>rfdetr-nano</code>, <code>rfdetr-small</code>, <code>rfdetr-medium</code>, <code>rfdetr-large</code>. Segmentation: <code>rfdetr-seg-*</code>.</td>
       <td><code>rfdetr-nano</code></td>
     </tr>
     <tr>
-      <td><code>--model.confidence</code></td>
+      <td><code>--detection.confidence</code></td>
       <td>Minimum confidence threshold. Lower values increase recall but may add noise.</td>
       <td><code>0.5</code></td>
     </tr>
     <tr>
-      <td><code>--model.device</code></td>
+      <td><code>--detection.device</code></td>
       <td>Compute device. Options: <code>auto</code>, <code>cpu</code>, <code>cuda</code>, <code>cuda:0</code>, <code>mps</code>.</td>
       <td><code>auto</code></td>
     </tr>
     <tr>
-      <td><code>--model.api_key</code></td>
+      <td><code>--detection.api-key</code></td>
       <td>Roboflow API key for custom hosted models.</td>
       <td>none</td>
     </tr>
     <tr>
-      <td><code>--classes</code></td>
+      <td><code>--filters.classes</code></td>
       <td>Comma-separated class names or IDs to track. Example: <code>person,car</code> or <code>0,2</code>.</td>
       <td>all</td>
     </tr>
+    <tr>
+      <td><code>--filters.track-ids</code></td>
+      <td>Comma-separated track IDs to keep in output. Example: <code>1,3,5</code>.</td>
+      <td>all</td>
+    </tr>
     <tr>
       <td><code>--tracker</code></td>
       <td>Tracking algorithm. Options: <code>bytetrack</code>, <code>sort</code>, <code>ocsort</code>, <code>botsort</code>.</td>
       <td><code>bytetrack</code></td>
     </tr>
     <tr>
-      <td><code>--tracker.lost_track_buffer</code></td>
-      <td>Frames to retain a track without detections. Higher values improve occlusion handling but risk ID drift.</td>
-      <td><code>30</code></td>
+      <td><code>--tracker.lost-track-buffer</code></td>
+      <td>Number of frames a lost track is kept before deletion. Applies to all trackers.</td>
+      <td>tracker default</td>
+    </tr>
+    <tr>
+      <td><code>--tracker.frame-rate</code></td>
+      <td>Source frame rate used by the tracker for time-based logic. Applies to all trackers.</td>
+      <td>tracker default</td>
+    </tr>
+    <tr>
+      <td><code>--tracker.track-activation-threshold</code></td>
+      <td>Detection confidence required to start a new track. Applies to <code>bytetrack</code>, <code>sort</code>, <code>botsort</code>.</td>
+      <td>tracker default</td>
     </tr>
     <tr>
-      <td><code>--tracker.track_activation_threshold</code></td>
-      <td>Minimum confidence to start a new track. Lower values catch more objects but increase false positives.</td>
-      <td><code>0.25</code></td>
+      <td><code>--tracker.minimum-consecutive-frames</code></td>
+      <td>Frames a new track must be matched before being confirmed. Applies to all trackers.</td>
+      <td>tracker default</td>
     </tr>
     <tr>
-      <td><code>--tracker.minimum_consecutive_frames</code></td>
-      <td>Consecutive detections required before a track is confirmed. Suppresses spurious detections.</td>
-      <td><code>3</code></td>
+      <td><code>--tracker.minimum-iou-threshold</code></td>
+      <td>IoU threshold for detection-to-track association. Applies to <code>bytetrack</code>, <code>sort</code>, <code>ocsort</code>.</td>
+      <td>tracker default</td>
     </tr>
     <tr>
-      <td><code>--tracker.minimum_iou_threshold</code></td>
-      <td>Minimum IoU overlap to match a detection to an existing track. Higher values require tighter alignment.</td>
-      <td><code>0.3</code></td>
+      <td colspan="3"><em>Algorithm-specific flags also exist (e.g. <code>--tracker.high-conf-det-threshold</code>, <code>--tracker.enable-cmc</code>/<code>--tracker.no-enable-cmc</code>, <code>--tracker.cmc-method</code>, <code>--tracker.delta-t</code>); each only takes effect when the selected <code>--tracker</code> exposes that parameter. Unset flags fall back to the tracker's own defaults.</em></td>
     </tr>
     <tr>
-      <td><code>--display</code></td>
+      <td><code>--show.display</code></td>
       <td>Opens a live preview window. Press <code>q</code> or <code>ESC</code> to quit.</td>
       <td><code>false</code></td>
     </tr>
     <tr>
-      <td><code>--show-boxes</code></td>
+      <td><code>--show.boxes</code></td>
       <td>Draw bounding boxes around tracked objects.</td>
       <td><code>true</code></td>
     </tr>
     <tr>
-      <td><code>--show-masks</code></td>
+      <td><code>--show.masks</code></td>
       <td>Draw segmentation masks. Only available with <code>rfdetr-seg-*</code> models.</td>
       <td><code>false</code></td>
     </tr>
     <tr>
-      <td><code>--show-confidence</code></td>
+      <td><code>--show.confidence</code></td>
       <td>Show detection confidence scores in labels.</td>
       <td><code>false</code></td>
     </tr>
     <tr>
-      <td><code>--show-labels</code></td>
+      <td><code>--show.labels</code></td>
       <td>Show class names in labels.</td>
       <td><code>false</code></td>
     </tr>
     <tr>
-      <td><code>--show-ids</code></td>
+      <td><code>--show.ids</code></td>
       <td>Show tracker IDs in labels.</td>
       <td><code>true</code></td>
     </tr>
     <tr>
-      <td><code>--show-trajectories</code></td>
+      <td><code>--show.trajectories</code></td>
       <td>Draw motion trails showing recent positions of each track.</td>
       <td><code>false</code></td>
     </tr>