feat: enhance CLI error handling with command suggestions

Author: chigwell

mcp/client/skilldock_mcp_client.py

@@ -2,12 +2,66 @@
 from __future__ import annotations
 
 import argparse
+import builtins
+import difflib
 import json
+import re
 import subprocess
 import sys
 from pathlib import Path
 from typing import Any
 
+try:
+    from rich.console import Console
+except Exception:  # pragma: no cover - optional runtime dependency
+    Console = None  # type: ignore[assignment]
+
+
+_INVALID_CHOICE_RE = re.compile(r"invalid choice: '([^']+)' \(choose from (.+)\)")
+
+
+def _console_print(*values: Any, sep: str = " ", end: str = "\n", file: Any | None = None, flush: bool = False) -> None:
+    if Console is None:
+        builtins.print(*values, sep=sep, end=end, file=file, flush=flush)
+        return
+
+    target = file if file is not None else sys.stdout
+    text = sep.join(str(v) for v in values)
+    console = Console(file=target, markup=False, highlight=False, soft_wrap=True)
+    console.print(text, end=end)
+    if flush and hasattr(target, "flush"):
+        target.flush()
+
+
+print = _console_print  # type: ignore[assignment]
+
+
+class SuggestingArgumentParser(argparse.ArgumentParser):
+    def add_subparsers(self, **kwargs: Any) -> Any:
+        kwargs.setdefault("parser_class", type(self))
+        return super().add_subparsers(**kwargs)
+
+    def error(self, message: str) -> None:
+        suggestion = self._build_command_suggestion(message)
+        if suggestion:
+            message = f"{message}\n{suggestion}"
+        self.print_usage(sys.stderr)
+        self.exit(2, f"{self.prog}: error: {message}\n")
+
+    def _build_command_suggestion(self, message: str) -> str | None:
+        match = _INVALID_CHOICE_RE.search(message)
+        if not match:
+            return None
+        invalid, raw_choices = match.groups()
+        choices = re.findall(r"'([^']+)'", raw_choices)
+        if not choices:
+            return None
+        suggestion = difflib.get_close_matches(invalid, choices, n=1, cutoff=0.45)
+        if not suggestion:
+            return None
+        best = suggestion[0]
+        return f"Did you mean '{best}'? Use the valid command: {best}"
+
 
 def _json_dumps(data: Any) -> str:
     return json.dumps(data, ensure_ascii=False, separators=(",", ":"))
@@ -159,7 +213,7 @@ def _default_server_cmd() -> list[str]:
 
 
 def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Minimal client for the local Skilldock MCP server.")
+    parser = SuggestingArgumentParser(description="Minimal client for the local Skilldock MCP server.")
     parser.add_argument(
         "--server-cmd",
         nargs="+",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "skilldock"
-version = "2026.03.11954"
+version = "2026.03.30837"
 description = "OpenAPI-driven Python SDK and CLI for the SkillDock.io API."
 readme = "README.md"
 license = { file = "LICENSE" }

src/skilldock/_version.py

@@ -2,5 +2,5 @@
 
 # NOTE: PEP 440 will normalize this version (e.g. 2026.02 -> 2026.2),
 # but keeping the requested format here is useful for humans.
-__version__ = "2026.03.11954"
+__version__ = "2026.03.30837"
 

src/skilldock/cli.py

@@ -3,6 +3,7 @@
 import argparse
 import base64
 import builtins
+import difflib
 import json
 import mimetypes
 import os
@@ -35,6 +36,7 @@
 
 _USD_AMOUNT_RE = re.compile(r"^\d+(?:\.\d{1,2})?$")
 _TON_AMOUNT_RE = re.compile(r"^\d+(?:\.\d{1,9})?$")
+_INVALID_CHOICE_RE = re.compile(r"invalid choice: '([^']+)' \(choose from (.+)\)")
 
 
 def _console_print(*values: Any, sep: str = " ", end: str = "\n", file: Any | None = None, flush: bool = False) -> None:
@@ -59,6 +61,33 @@ def _console_print(*values: Any, sep: str = " ", end: str = "\n", file: Any | No
 print = _console_print  # type: ignore[assignment]
 
 
+class SkilldockArgumentParser(argparse.ArgumentParser):
+    def add_subparsers(self, **kwargs: Any) -> Any:
+        kwargs.setdefault("parser_class", type(self))
+        return super().add_subparsers(**kwargs)
+
+    def error(self, message: str) -> None:
+        suggestion = self._build_command_suggestion(message)
+        if suggestion:
+            message = f"{message}\n{suggestion}"
+        self.print_usage(sys.stderr)
+        self.exit(2, f"{self.prog}: error: {message}\n")
+
+    def _build_command_suggestion(self, message: str) -> str | None:
+        match = _INVALID_CHOICE_RE.search(message)
+        if not match:
+            return None
+        invalid, raw_choices = match.groups()
+        choices = re.findall(r"'([^']+)'", raw_choices)
+        if not choices:
+            return None
+        suggestion = difflib.get_close_matches(invalid, choices, n=1, cutoff=0.45)
+        if not suggestion:
+            return None
+        best = suggestion[0]
+        return f"Did you mean '{best}'? Use the valid command: {best}"
+
+
 def _jsonish(v: str) -> Any:
     v = v.strip()
     if v == "":
@@ -601,8 +630,8 @@ def _bootstrap_personal_token_after_oauth(
         client.close()
 
 
-def build_parser() -> argparse.ArgumentParser:
-    p = argparse.ArgumentParser(
+def build_parser() -> SkilldockArgumentParser:
+    p = SkilldockArgumentParser(
         prog="skilldock",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         description="SkillDock API client (OpenAPI-driven).",

src/skilldock/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import base64
+import builtins
 import json
 import sys
 import time
@@ -11,10 +12,28 @@
 
 import httpx
 
+try:
+    from rich.console import Console
+except Exception:  # pragma: no cover - optional runtime dependency
+    Console = None  # type: ignore[assignment]
+
 from .config import DEFAULT_OPENAPI_URL, DEFAULT_TIMEOUT_S
 from .openapi import AuthStrategy, OpenAPIOperation, OpenAPISpec, load_openapi, parse_spec
 
 
+def _console_print(*values: Any, sep: str = " ", end: str = "\n", file: Any | None = None, flush: bool = False) -> None:
+    if Console is None:
+        builtins.print(*values, sep=sep, end=end, file=file, flush=flush)
+        return
+
+    target = file if file is not None else sys.stdout
+    text = sep.join(str(v) for v in values)
+    console = Console(file=target, markup=False, highlight=False, soft_wrap=True)
+    console.print(text, end=end)
+    if flush and hasattr(target, "flush"):
+        target.flush()
+
+
 class SkilldockError(RuntimeError):
     pass
 
@@ -267,7 +286,7 @@ def _warn_auth_optional_fallback(self, message: str) -> None:
         if self._auth_optional_warning_printed:
             return
         self._auth_optional_warning_printed = True
-        print(f"warning: {message}", file=sys.stderr)
+        _console_print(f"warning: {message}", file=sys.stderr)
 
     def _should_retry_unauthenticated(self, err: SkilldockHTTPError) -> bool:
         if err.status_code in (401, 403):

tests/test_cli.py

@@ -814,6 +814,28 @@ def test_help_topic_prints_argparse_help_for_command(self) -> None:
         self.assertIn("usage: skilldock skills", out)
         self.assertIn("search              Search skills", out)
 
+    def test_invalid_top_level_command_suggests_closest_match(self) -> None:
+        with patch("sys.stderr", new=io.StringIO()) as stderr:
+            with self.assertRaises(SystemExit) as ctx:
+                main(["skils"])
+
+        self.assertEqual(ctx.exception.code, 2)
+        err = stderr.getvalue()
+        self.assertIn("invalid choice: 'skils'", err)
+        self.assertIn("Did you mean 'skills'?", err)
+        self.assertIn("Use the valid command: skills", err)
+
+    def test_invalid_nested_command_suggests_closest_match(self) -> None:
+        with patch("sys.stderr", new=io.StringIO()) as stderr:
+            with self.assertRaises(SystemExit) as ctx:
+                main(["auth", "logn"])
+
+        self.assertEqual(ctx.exception.code, 2)
+        err = stderr.getvalue()
+        self.assertIn("invalid choice: 'logn'", err)
+        self.assertIn("Did you mean 'login'?", err)
+        self.assertIn("Use the valid command: login", err)
+
 
 class TestHttpErrorFormatting(unittest.TestCase):
     def test_format_402_purchase_required(self) -> None: