fix(cli): fix QA issues — fork output, video error, version help, timestamps

- workflow fork: read 'workflow' key from API response (was looking for 'url')
- video status: provide actionable error with hint for not-found jobs
- version create: add settings JSON example in --help epilog
- annotation batch/job: convert Firestore timestamps to ISO 8601

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: yeldarby

roboflow/cli/handlers/annotation.py

@@ -75,6 +75,24 @@ def _add_job(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
     job_parser.set_defaults(func=lambda args: job_parser.print_help())
 
 
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _normalize_timestamps(obj):
+    """Recursively convert Firestore timestamp dicts ({"_seconds": N, "_nanoseconds": N}) to ISO 8601 strings."""
+    from datetime import datetime, timezone
+
+    if isinstance(obj, dict):
+        if "_seconds" in obj and "_nanoseconds" in obj and len(obj) == 2:
+            return datetime.fromtimestamp(obj["_seconds"], tz=timezone.utc).isoformat()
+        return {k: _normalize_timestamps(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_normalize_timestamps(item) for item in obj]
+    return obj
+
+
 # ---------------------------------------------------------------------------
 # handlers
 # ---------------------------------------------------------------------------
@@ -117,6 +135,7 @@ def _batch_list(args: argparse.Namespace) -> None:
         return
 
     batches = data if isinstance(data, list) else data.get("batches", data)
+    batches = _normalize_timestamps(batches)
 
     table = format_table(
         batches if isinstance(batches, list) else [],
@@ -141,6 +160,7 @@ def _batch_get(args: argparse.Namespace) -> None:
         output_error(args, str(exc), exit_code=3)
         return
 
+    data = _normalize_timestamps(data)
     batch = data.get("batch", data) if isinstance(data, dict) else data
 
     lines = []
@@ -169,6 +189,7 @@ def _job_list(args: argparse.Namespace) -> None:
         return
 
     jobs = data if isinstance(data, list) else data.get("jobs", data)
+    jobs = _normalize_timestamps(jobs)
 
     table = format_table(
         jobs if isinstance(jobs, list) else [],
@@ -193,6 +214,7 @@ def _job_get(args: argparse.Namespace) -> None:
         output_error(args, str(exc), exit_code=3)
         return
 
+    data = _normalize_timestamps(data)
     job = data.get("job", data) if isinstance(data, dict) else data
 
     lines = []

roboflow/cli/handlers/version.py

@@ -2,11 +2,15 @@
 
 from __future__ import annotations
 
+import argparse
 import re
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    import argparse
+
+class _RawEpilogFormatter(argparse.HelpFormatter):
+    """Formatter that preserves raw text in the epilog while wrapping everything else."""
+
+    def _fill_text(self, text: str, width: int, indent: str) -> str:
+        return text
 
 
 def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
@@ -40,7 +44,19 @@ def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[ty
     export_parser.set_defaults(func=_export)
 
     # --- version create ---
-    create_parser = version_subs.add_parser("create", help="Create a new dataset version")
+    create_parser = version_subs.add_parser(
+        "create",
+        help="Create a new dataset version",
+        epilog=(
+            "Settings JSON example:\n"
+            '  {"augmentation": {"flip": {"horizontal": true, "vertical": false},\n'
+            '    "rotate": {"degrees": 15}, "brightness": {"percent": 25}},\n'
+            '   "preprocessing": {"auto-orient": true, "resize": {"width": 640,\n'
+            '    "height": 640, "format": "Stretch to"}}}\n\n'
+            "See https://docs.roboflow.com/datasets/create-a-dataset-version for all options."
+        ),
+        formatter_class=_RawEpilogFormatter,
+    )
     create_parser.add_argument("-p", "--project", dest="project", required=True, help="Project ID")
     create_parser.add_argument(
         "--settings", dest="settings", required=True, help="Path to JSON file with augmentation/preprocessing config"

roboflow/cli/handlers/video.py

@@ -72,7 +72,16 @@ def _video_status(args: argparse.Namespace) -> None:
     try:
         data = rfapi.get_video_job_status(api_key, args.job_id)
     except rfapi.RoboflowError as exc:
-        output_error(args, str(exc), exit_code=3)
+        msg = str(exc)
+        if "NOT FOUND" in msg.upper():
+            output_error(
+                args,
+                f"Video job '{args.job_id}' not found.",
+                hint="Run 'roboflow video infer' to start a video job.",
+                exit_code=3,
+            )
+        else:
+            output_error(args, msg, exit_code=3)
         return
 
     status = data.get("status", "unknown")

roboflow/cli/handlers/workflow.py

@@ -331,7 +331,7 @@ def _fork_workflow(args: argparse.Namespace) -> None:
         output_error(args, str(exc))
         return
 
-    new_url = data.get("url", data.get("workflow_url", "")) if isinstance(data, dict) else ""
+    new_url = data.get("workflow", data.get("url", data.get("workflow_url", ""))) if isinstance(data, dict) else ""
     result = {"status": "forked", "source": args.workflow_url, "new_url": new_url}
     text = f"Forked workflow: {args.workflow_url} -> {new_url}"
     output(args, result, text=text)