Command descriptions

Author: davegaeddert

example/app/cli.py

@@ -17,7 +17,7 @@ def cli():
 @cli.command()
 @click.argument("email")
 def enable_admin_user(email):
-    """Enable admin privileges for a user."""
+    """Enable admin privileges for a user"""
     result = User.query.filter(email=email).update(is_admin=True)
     if result:
         click.echo(f"User {email} is now an admin.")

plain-api/plain/api/cli.py

@@ -14,8 +14,7 @@
 @register_cli("api")
 @click.group()
 def cli() -> None:
-    """API commands."""
-    pass
+    """API commands"""
 
 
 @cli.command()

plain-cache/plain/cache/cli.py

@@ -8,11 +8,12 @@
 @register_cli("cache")
 @click.group()
 def cli() -> None:
-    pass
+    """Cache management"""
 
 
 @cli.command()
 def clear_expired() -> None:
+    """Clear expired cache entries"""
     click.echo("Clearing expired cache items...")
     result = CachedItem.query.expired().delete()
     click.echo(f"Deleted {result[0]} expired cache items.")
@@ -21,6 +22,7 @@ def clear_expired() -> None:
 @cli.command()
 @click.option("--force", is_flag=True)
 def clear_all(force: bool) -> None:
+    """Clear all cache entries"""
     if not force and not click.confirm(
         "Are you sure you want to delete all cache items?"
     ):
@@ -32,6 +34,7 @@ def clear_all(force: bool) -> None:
 
 @cli.command()
 def stats() -> None:
+    """Show cache statistics"""
     total = CachedItem.query.count()
     expired = CachedItem.query.expired().count()
     unexpired = CachedItem.query.unexpired().count()

plain-code/plain/code/cli.py

@@ -30,7 +30,7 @@ def cli() -> None:
 @click.option("--force", is_flag=True, help="Reinstall even if up to date")
 @click.pass_context
 def install(ctx: click.Context, force: bool) -> None:
-    """Install or update the Biome standalone per configuration."""
+    """Install or update Biome binary"""
     config = get_code_config()
 
     if not config.get("biome", {}).get("enabled", True):
@@ -58,7 +58,7 @@ def install(ctx: click.Context, force: bool) -> None:
 @without_runtime_setup
 @cli.command()
 def update() -> None:
-    """Update the Biome standalone binary to the latest release."""
+    """Update Biome to latest version"""
     config = get_code_config()
 
     if not config.get("biome", {}).get("enabled", True):
@@ -76,7 +76,7 @@ def update() -> None:
 @click.pass_context
 @click.argument("path", default=".")
 def check(ctx: click.Context, path: str) -> None:
-    """Check the given path for formatting or linting issues."""
+    """Check for formatting and linting issues"""
     ruff_args = ["--config", str(DEFAULT_RUFF_CONFIG)]
     config = get_code_config()
 
@@ -127,7 +127,7 @@ def maybe_exit(return_code: int) -> None:
 @click.option("--unsafe-fixes", is_flag=True, help="Apply ruff unsafe fixes")
 @click.option("--add-noqa", is_flag=True, help="Add noqa comments to suppress errors")
 def fix(ctx: click.Context, path: str, unsafe_fixes: bool, add_noqa: bool) -> None:
-    """Lint and format the given path."""
+    """Fix formatting and linting issues"""
     ruff_args = ["--config", str(DEFAULT_RUFF_CONFIG)]
     config = get_code_config()
 

plain-dev/plain/dev/cli.py

@@ -129,7 +129,7 @@ def cli(
     start: bool,
     stop: bool,
 ) -> None:
-    """Start local development"""
+    """Local development server"""
     if ctx.invoked_subcommand:
         return
 
@@ -223,7 +223,7 @@ def _connect() -> subprocess.CompletedProcess[bytes]:
 @click.option("--start", is_flag=True, help="Start in the background")
 @click.option("--stop", is_flag=True, help="Stop the background process")
 def services(start: bool, stop: bool) -> None:
-    """Start additional services defined in pyproject.toml"""
+    """Start additional development services"""
 
     if start and stop:
         raise click.UsageError(
@@ -263,7 +263,7 @@ def services(start: bool, stop: bool) -> None:
 @click.option("--path", is_flag=True, help="Output log file path")
 @click.option("--services", is_flag=True, help="Show logs for services")
 def logs(follow: bool, pid: int | None, path: bool, services: bool) -> None:
-    """Show logs from recent plain dev runs."""
+    """Show recent development logs"""
 
     if services:
         log_dir = PLAIN_TEMP_PATH / "dev" / "logs" / "services"
@@ -299,7 +299,7 @@ def logs(follow: bool, pid: int | None, path: bool, services: bool) -> None:
 )
 @click.argument("entrypoint", required=False)
 def entrypoint(show_list: bool, entrypoint: str | None) -> None:
-    """Entrypoints registered under plain.dev"""
+    """Run registered development entrypoints"""
     if not show_list and not entrypoint:
         raise click.UsageError("Please provide an entrypoint name or use --list")
 

plain-dev/plain/dev/contribute/cli.py

@@ -20,7 +20,7 @@
 )
 @click.argument("packages", nargs=-1)
 def cli(packages: tuple[str, ...], repo: str, reset: bool, all_packages: bool) -> None:
-    """Contribute to plain by linking packages locally."""
+    """Link Plain packages for local development"""
 
     if reset:
         click.secho("Undoing any changes to pyproject.toml and uv.lock", bold=True)

plain-jobs/plain/jobs/cli.py

@@ -22,7 +22,7 @@
 @register_cli("jobs")
 @click.group()
 def cli() -> None:
-    pass
+    """Background job management"""
 
 
 @cli.command()
@@ -75,7 +75,7 @@ def worker(
     stats_every: int,
     reload: bool,
 ) -> None:
-    """Run the job worker."""
+    """Run the job worker"""
     jobs_schedule = load_schedule(settings.JOBS_SCHEDULE)
 
     if reload:
@@ -140,7 +140,7 @@ def _shutdown(signalnum: int, _: Any) -> None:
 
 @cli.command()
 def clear() -> None:
-    """Clear all completed job results in all queues."""
+    """Clear completed job results"""
     cutoff = timezone.now() - datetime.timedelta(
         seconds=settings.JOBS_RESULTS_RETENTION
     )
@@ -151,7 +151,7 @@ def clear() -> None:
 
 @cli.command()
 def stats() -> None:
-    """Stats across all queues."""
+    """Show job queue statistics"""
     pending = JobRequest.query.count()
     processing = JobProcess.query.count()
 
@@ -168,7 +168,7 @@ def stats() -> None:
 
 @cli.command()
 def purge() -> None:
-    """Delete all running and pending jobs regardless of queue."""
+    """Delete all pending and running jobs"""
     if not click.confirm(
         "Are you sure you want to clear all running and pending jobs? This will delete all current Jobs and JobRequests"
     ):
@@ -184,7 +184,7 @@ def purge() -> None:
 @cli.command()
 @click.argument("job_class_name", type=str)
 def run(job_class_name: str) -> None:
-    """Run a job class directly (and not using a worker)."""
+    """Run a job directly without a worker"""
     job = jobs_registry.load_job(job_class_name, {"args": [], "kwargs": {}})
     click.secho("Loaded job: ", bold=True, nl=False)
     print(job)
@@ -193,7 +193,7 @@ def run(job_class_name: str) -> None:
 
 @cli.command("list")
 def list_jobs() -> None:
-    """List all registered jobs."""
+    """List all registered jobs"""
     for name, job_class in jobs_registry.jobs.items():
         click.secho(f"{name}", bold=True, nl=False)
         # Get description from class docstring

plain-models/plain/models/backups/cli.py

@@ -7,12 +7,10 @@
 import click
 
 from plain.cli import register_cli
-from plain.cli.runtime import common_command
 
 from .core import DatabaseBackups
 
 
-@common_command
 @register_cli("backups", shortcut_for="models")
 @click.group("backups")
 def cli() -> None:
@@ -22,6 +20,7 @@ def cli() -> None:
 
 @cli.command("list")
 def list_backups() -> None:
+    """List database backups"""
     backups_handler = DatabaseBackups()
     backups = backups_handler.find_backups()
     if not backups:
@@ -45,6 +44,7 @@ def list_backups() -> None:
 @click.option("--pg-dump", default="pg_dump", envvar="PG_DUMP")
 @click.argument("backup_name", default="")
 def create_backup(backup_name: str, pg_dump: str) -> None:
+    """Create a database backup"""
     backups_handler = DatabaseBackups()
 
     if not backup_name:
@@ -67,6 +67,7 @@ def create_backup(backup_name: str, pg_dump: str) -> None:
 @click.option("--pg-restore", default="pg_restore", envvar="PG_RESTORE")
 @click.argument("backup_name", default="")
 def restore_backup(backup_name: str, latest: bool, pg_restore: str) -> None:
+    """Restore a database backup"""
     backups_handler = DatabaseBackups()
 
     if backup_name and latest:
@@ -94,6 +95,7 @@ def restore_backup(backup_name: str, latest: bool, pg_restore: str) -> None:
 @cli.command("delete")
 @click.argument("backup_name")
 def delete_backup(backup_name: str) -> None:
+    """Delete a database backup"""
     backups_handler = DatabaseBackups()
     try:
         backups_handler.delete(backup_name)
@@ -106,6 +108,7 @@ def delete_backup(backup_name: str) -> None:
 @cli.command("clear")
 @click.confirmation_option(prompt="Are you sure you want to delete all backups?")
 def clear_backups() -> None:
+    """Clear all database backups"""
     backups_handler = DatabaseBackups()
     backups = backups_handler.find_backups()
     for backup in backups:

plain-models/plain/models/cli.py

@@ -45,7 +45,7 @@
 @register_cli("models")
 @click.group()
 def cli() -> None:
-    pass
+    """Database model management"""
 
 
 cli.add_command(backups_cli)
@@ -54,7 +54,7 @@ def cli() -> None:
 @cli.command()
 @click.argument("parameters", nargs=-1)
 def db_shell(parameters: tuple[str, ...]) -> None:
-    """Runs the command-line client for specified database, or the default database if none is provided."""
+    """Open an interactive database shell"""
     try:
         db_connection.client.runshell(list(parameters))
     except FileNotFoundError:
@@ -114,7 +114,7 @@ def db_wait() -> None:
     help="Only show models from packages that start with 'app'.",
 )
 def list_models(package_labels: tuple[str, ...], app_only: bool) -> None:
-    """List installed models."""
+    """List all installed models"""
 
     packages = set(package_labels)
 
@@ -176,7 +176,7 @@ def makemigrations(
     check: bool,
     verbosity: int,
 ) -> None:
-    """Creates new migration(s) for packages."""
+    """Create new database migrations"""
 
     written_files: list[str] = []
     interactive = not no_input
@@ -397,7 +397,7 @@ def migrate(
     atomic_batch: bool | None,
     quiet: bool,
 ) -> None:
-    """Updates database schema. Manages both packages with migrations and those without."""
+    """Apply database migrations"""
 
     def migration_progress_callback(
         action: str,
@@ -713,7 +713,7 @@ def describe_operation(operation: Any) -> tuple[str, bool]:
 def show_migrations(
     package_labels: tuple[str, ...], format: str, verbosity: int
 ) -> None:
-    """Shows all available migrations for the current project"""
+    """Show all available migrations"""
 
     def _validate_package_names(package_names: tuple[str, ...]) -> None:
         has_bad_names = False
@@ -834,7 +834,7 @@ def print_deps(node: Any) -> str:
     help="Skip confirmation prompt (for non-interactive use).",
 )
 def prune_migrations(yes: bool) -> None:
-    """Show and optionally remove stale migration records from the database."""
+    """Prune stale migration records"""
     # Load migrations from disk and database
     loader = MigrationLoader(db_connection, ignore_no_migrations=True)
     recorder = MigrationRecorder(db_connection)
@@ -962,9 +962,7 @@ def squash_migrations(
     squashed_name: str | None,
     verbosity: int,
 ) -> None:
-    """
-    Squashes an existing set of migrations (from first until specified) into a single new one.
-    """
+    """Squash multiple migrations into one"""
     interactive = not no_input
 
     def find_migration(