feat: shell completions

Author: 404Simon

README.md

@@ -36,6 +36,21 @@ CLI outputs:
 - Optional per-image skeleton outputs (default: `.npy`)
 - Optional per-image branch tables when `output.write_branch_csv=true`
 
+### Shell completions
+
+```sh
+# zsh
+eval "$(vesskel completions zsh)"
+
+# bash
+eval "$(vesskel completions bash)"
+
+# PowerShell
+vesskel completions powershell | Out-String | Invoke-Expression
+```
+
+Add the appropriate line to your shell rc for persistent tab-completion.
+
 ## Tests
 
 ```sh

pyproject.toml

@@ -6,6 +6,7 @@ description = "2D and 3D Skeletonization and Graph-based Analysis"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
+    "argcomplete>=3.6.0",
     "numba>=0.65.0",
     "numpy>=2.4.4",
     "pillow>=12.2.0",

uv.lock

@@ -10,6 +10,7 @@
 from typing import Iterable
 
 import numpy as np
+from argcomplete import autocomplete, shellcode
 from PIL import Image
 
 from vesskel.config import (
@@ -76,6 +77,20 @@ def _parse_args() -> argparse.Namespace:
     )
     validate_parser.add_argument("--config", required=True, help="Config JSON path.")
 
+    completions_parser = subparsers.add_parser(
+        "completions",
+        help="Print shell completion script to stdout.",
+    )
+    completions_parser.add_argument(
+        "shell",
+        choices=("bash", "zsh", "powershell"),
+        help="Target shell.",
+    )
+
+    try:
+        autocomplete(parser)
+    except ImportError:
+        pass
     return parser.parse_args()
 
 
@@ -244,6 +259,12 @@ def _validate_config(args: argparse.Namespace) -> int:
     return 0
 
 
+def _completions(args: argparse.Namespace) -> int:
+
+    print(shellcode(["vesskel"], shell=args.shell))
+    return 0
+
+
 def main() -> int:
     args = _parse_args()
     if args.command == "run":
@@ -252,6 +273,8 @@ def main() -> int:
         return _config_init(args)
     if args.command == "validate-config":
         return _validate_config(args)
+    if args.command == "completions":
+        return _completions(args)
     raise ValueError(f"Unknown command: {args.command}")