Improved CLI error reporting for users (#458)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

ultralytics/yolo/cli.py

@@ -4,13 +4,53 @@ import argparse
 import shutil
 from pathlib import Path
 
-from hydra import compose, initialize
-
-from ultralytics import hub, yolo
-from ultralytics.yolo.utils import DEFAULT_CONFIG, HELP_MSG, LOGGER, PREFIX, print_settings, yaml_load
+from ultralytics import __version__, yolo
+from ultralytics.yolo.utils import DEFAULT_CONFIG, LOGGER, PREFIX, checks, print_settings, yaml_load
 
 DIR = Path(__file__).parent
 
+CLI_HELP_MSG = \
+    """
+    YOLOv8 CLI Usage examples:
+
+    1. Install the ultralytics package:
+
+        pip install ultralytics
+
+    2. Train, Val, Predict and Export using 'yolo' commands of the form:
+
+            yolo TASK MODE ARGS
+
+            Where   TASK (optional) is one of [detect, segment, classify]
+                    MODE (required) is one of [train, val, predict, export]
+                    ARGS (optional) are any number of custom 'arg=value' pairs like 'imgsz=320' that override defaults.
+                        For a full list of available ARGS see https://docs.ultralytics.com/config.
+
+        Train a detection model for 10 epochs with an initial learning_rate of 0.01
+            yolo detect train data=coco128.yaml model=yolov8n.pt epochs=10 lr0=0.01
+
+        Predict a YouTube video using a pretrained segmentation model at image size 320:
+            yolo segment predict model=yolov8n-seg.pt source=https://youtu.be/Zgi9g1ksQHc imgsz=320
+
+        Validate a pretrained detection model at batch-size 1 and image size 640:
+            yolo detect val model=yolov8n.pt data=coco128.yaml batch=1 imgsz=640
+
+        Export a YOLOv8n classification model to ONNX format at image size 224 by 128 (no TASK required)
+            yolo export model=yolov8n-cls.pt format=onnx imgsz=224,128
+
+    3. Run special commands:
+
+        yolo help
+        yolo checks
+        yolo version
+        yolo settings
+        yolo copy-config
+
+    Docs: https://docs.ultralytics.com/cli
+    Community: https://community.ultralytics.com
+    GitHub: https://github.com/ultralytics/ultralytics
+    """
+
 
 def cli(cfg):
     """
@@ -28,20 +68,16 @@ def cli(cfg):
     task, mode = cfg.task.lower(), cfg.mode.lower()
 
     # Mapping from task to module
-    task_module_map = {"detect": yolo.v8.detect, "segment": yolo.v8.segment, "classify": yolo.v8.classify}
-    module = task_module_map.get(task)
+    tasks = {"detect": yolo.v8.detect, "segment": yolo.v8.segment, "classify": yolo.v8.classify}
+    module = tasks.get(task)
     if not module:
-        raise SyntaxError(f"task not recognized. Choices are {', '.join(task_module_map.keys())}")
+        raise SyntaxError(f"yolo task={task} is invalid. Valid tasks are: {', '.join(tasks.keys())}\n{CLI_HELP_MSG}")
 
     # Mapping from mode to function
-    mode_func_map = {
-        "train": module.train,
-        "val": module.val,
-        "predict": module.predict,
-        "export": yolo.engine.exporter.export}
-    func = mode_func_map.get(mode)
+    modes = {"train": module.train, "val": module.val, "predict": module.predict, "export": yolo.engine.exporter.export}
+    func = modes.get(mode)
     if not func:
-        raise SyntaxError(f"mode not recognized. Choices are {', '.join(mode_func_map.keys())}")
+        raise SyntaxError(f"yolo mode={mode} is invalid. Valid modes are: {', '.join(modes.keys())}\n{CLI_HELP_MSG}")
 
     func(cfg)
 
@@ -68,8 +104,9 @@ def entrypoint():
     tasks = 'detect', 'segment', 'classify'
     modes = 'train', 'val', 'predict', 'export'
     special_modes = {
-        'checks': hub.checks,
-        'help': lambda: LOGGER.info(HELP_MSG),
+        'help': lambda: LOGGER.info(CLI_HELP_MSG),
+        'checks': checks.check_yolo,
+        'version': lambda: LOGGER.info(__version__),
         'settings': print_settings,
         'copy-config': copy_default_config}
 
@@ -87,8 +124,17 @@ def entrypoint():
             return
         elif a in defaults and defaults[a] is False:
             overrides.append(f'{a}=True')  # auto-True for default False args, i.e. yolo show
+        elif a in defaults:
+            raise SyntaxError(f"'{a}' is a valid YOLO argument but is missing an '=' sign to set its value, "
+                              f"i.e. try '{a}={defaults[a]}'"
+                              f"\n{CLI_HELP_MSG}")
         else:
-            raise (SyntaxError(f"'{a}' is not a valid yolo argument\n{HELP_MSG}"))
+            raise SyntaxError(
+                f"'{a}' is not a valid YOLO argument. For a full list of valid arguments see "
+                f"https://github.com/ultralytics/ultralytics/blob/main/ultralytics/yolo/configs/default.yaml"
+                f"\n{CLI_HELP_MSG}")
+
+    from hydra import compose, initialize
 
     with initialize(version_base=None, config_path=str(DEFAULT_CONFIG.parent.relative_to(DIR)), job_name="YOLO"):
         cfg = compose(config_name=DEFAULT_CONFIG.name, overrides=overrides)

ultralytics/yolo/utils/checks.py

@@ -3,7 +3,9 @@
 import glob
 import inspect
 import math
+import os
 import platform
+import shutil
 import urllib
 from pathlib import Path
 from subprocess import check_output
@@ -12,10 +14,12 @@ from typing import Optional
 import cv2
 import numpy as np
 import pkg_resources as pkg
+import psutil
 import torch
+from IPython import display
 
 from ultralytics.yolo.utils import (AUTOINSTALL, FONT, LOGGER, ROOT, USER_CONFIG_DIR, TryExcept, colorstr, emojis,
-                                    is_docker, is_jupyter_notebook)
+                                    is_colab, is_docker, is_jupyter_notebook)
 
 
 def is_ascii(s) -> bool:
@@ -245,6 +249,26 @@ def check_imshow(warn=False):
         return False
 
 
+def check_yolo(verbose=True):
+    from ultralytics.yolo.utils.torch_utils import select_device
+
+    if is_colab():
+        shutil.rmtree('sample_data', ignore_errors=True)  # remove colab /sample_data directory
+
+    if verbose:
+        # System info
+        gib = 1 << 30  # bytes per GiB
+        ram = psutil.virtual_memory().total
+        total, used, free = shutil.disk_usage("/")
+        display.clear_output()
+        s = f'({os.cpu_count()} CPUs, {ram / gib:.1f} GB RAM, {(total - free) / gib:.1f}/{total / gib:.1f} GB disk)'
+    else:
+        s = ''
+
+    select_device(newline=False)
+    LOGGER.info(f'Setup complete ✅ {s}')
+
+
 def git_describe(path=ROOT):  # path must be a directory
     # Return human-readable git description, i.e. v5.0-5-g3e25f1e https://git-scm.com/docs/git-describe
     try: