From 855a79853b93b6db6699e26698c9d6e99fdd79a2 Mon Sep 17 00:00:00 2001
From: mbsantiago <santiago.mbal@gmail.com>
Date: Wed, 6 May 2026 14:47:29 +0100
Subject: [PATCH] docs: refine CLI command docstrings

---
 src/batdetect2/cli/compat.py   |  1 -
 src/batdetect2/cli/data.py     | 10 +++++-----
 src/batdetect2/cli/evaluate.py | 24 ++++++++++++++++--------
 src/batdetect2/cli/finetune.py | 20 ++++++++++----------
 4 files changed, 31 insertions(+), 24 deletions(-)

diff --git a/src/batdetect2/cli/compat.py b/src/batdetect2/cli/compat.py
index dad391c..238e775 100644
--- a/src/batdetect2/cli/compat.py
+++ b/src/batdetect2/cli/compat.py
@@ -1,5 +1,4 @@
 import os
-import warnings
 
 import click
 
diff --git a/src/batdetect2/cli/data.py b/src/batdetect2/cli/data.py
index fc2a610..d488883 100644
--- a/src/batdetect2/cli/data.py
+++ b/src/batdetect2/cli/data.py
@@ -7,9 +7,9 @@ from batdetect2.cli.base import cli
 __all__ = ["data"]
 
 
-@cli.group(short_help="Inspect and convert datasets.")
+@cli.group(short_help="Inspect and manage datasets.")
 def data():
-    """Inspect and convert dataset configuration files."""
+    """Inspect and manage dataset configuration files."""
 
 
 @data.command(short_help="Print dataset summary information.")
@@ -64,7 +64,7 @@ def summary(
         base_dir=base_dir,
     )
 
-    print(f"Number of annotated clips: {len(dataset)}")
+    click.echo(f"Number of annotated clips: {len(dataset)}")
 
     if targets_path is None:
         return
@@ -73,7 +73,7 @@ def summary(
 
     summary = compute_class_summary(dataset, targets)
 
-    print(summary.sort_values("class_name").to_markdown())
+    click.echo(summary.sort_values("class_name").to_markdown())
 
 
 @data.command(short_help="Convert dataset config to annotation set.")
@@ -200,6 +200,6 @@ def convert(
         if not audio_dir.is_absolute():
             audio_dir = audio_dir.resolve()
 
-        print(f"Using audio directory: {audio_dir}")
+        click.echo(f"Using audio directory: {audio_dir}")
 
     io.save(annotation_set, output, audio_dir=audio_dir)
diff --git a/src/batdetect2/cli/evaluate.py b/src/batdetect2/cli/evaluate.py
index 9007521..c2db7e9 100644
--- a/src/batdetect2/cli/evaluate.py
+++ b/src/batdetect2/cli/evaluate.py
@@ -12,8 +12,16 @@ DEFAULT_OUTPUT_DIR = Path("outputs") / "evaluation"
 
 
 @cli.command(name="evaluate", short_help="Evaluate a model checkpoint.")
-@click.argument("model_path", type=str)
 @click.argument("test_dataset", type=click.Path(exists=True))
+@click.option(
+    "--model",
+    "model_path",
+    type=str,
+    help=(
+        "Path to a checkpoint, checkpoint alias, or a Hugging Face "
+        "URI to fine-tune from. Defaults to uk_same"
+    ),
+)
 @click.option(
     "--audio-config",
     type=click.Path(exists=True),
@@ -74,14 +82,14 @@ DEFAULT_OUTPUT_DIR = Path("outputs") / "evaluation"
     default=0,
 )
 def evaluate_command(
-    model_path: str,
     test_dataset: Path,
-    base_dir: Path,
-    audio_config: Path | None,
-    evaluation_config: Path | None,
-    inference_config: Path | None,
-    outputs_config: Path | None,
-    logging_config: Path | None,
+    model_path: str | None = None,
+    base_dir: Path | None = None,
+    audio_config: Path | None = None,
+    evaluation_config: Path | None = None,
+    inference_config: Path | None = None,
+    outputs_config: Path | None = None,
+    logging_config: Path | None = None,
     output_dir: Path = DEFAULT_OUTPUT_DIR,
     num_workers: int = 0,
     experiment_name: str | None = None,
diff --git a/src/batdetect2/cli/finetune.py b/src/batdetect2/cli/finetune.py
index 53fd1ba..c98f23a 100644
--- a/src/batdetect2/cli/finetune.py
+++ b/src/batdetect2/cli/finetune.py
@@ -13,15 +13,6 @@ __all__ = ["finetune_command"]
     name="finetune", short_help="Fine-tune a checkpoint on new targets."
 )
 @click.argument("train_dataset", type=click.Path(exists=True))
-@click.option(
-    "--model",
-    "model_path",
-    type=str,
-    help=(
-        "Path to a checkpoint, bundled checkpoint alias, or a Hugging Face "
-        "URI to fine-tune from. Defaults to uk_same"
-    ),
-)
 @click.option(
     "--targets",
     "targets_config",
@@ -29,6 +20,15 @@ __all__ = ["finetune_command"]
     type=click.Path(exists=True),
     help="Path to the new targets config file.",
 )
+@click.option(
+    "--model",
+    "model_path",
+    type=str,
+    help=(
+        "Path to a checkpoint, checkpoint alias, or a Hugging Face "
+        "URI to fine-tune from. Defaults to uk_same"
+    ),
+)
 @click.option(
     "--val-dataset",
     type=click.Path(exists=True),
@@ -108,8 +108,8 @@ __all__ = ["finetune_command"]
 )
 def finetune_command(
     train_dataset: Path,
-    model_path: str | None,
     targets_config: Path,
+    model_path: str | None = None,
     val_dataset: Path | None = None,
     ckpt_dir: Path | None = None,
     log_dir: Path | None = None,