Refactor CLI commands and update documentation for improved clarity and functionality

Author: luisggoncalves

README.md

@@ -53,9 +53,9 @@ sqlcompare table analytics.fact_sales analytics.fact_sales_new id
 That command prints a **diff_id**. Use it for follow-up analysis:
 
 ```bash
-sqlcompare analyze-diff <diff_id> --stats
-sqlcompare analyze-diff <diff_id> --column revenue --limit 100
-sqlcompare analyze-diff <diff_id> --missing-current
+sqlcompare inspect <diff_id> --stats
+sqlcompare inspect <diff_id> --column revenue --limit 100
+sqlcompare inspect <diff_id> --missing-current
 ```
 
 ---

examples/row_compare.md

@@ -45,6 +45,6 @@ Rows only in previous dataset: 1
 | 1  |  name  | alpha  |  alfa   |
 | 1  | amount |   10   |   11    |
 +----+--------+--------+---------+
-🔎 To review the diff, run: sqlcompare analyze-diff compare_sqlcompare_dataset_dataset_998aa249_previous_sqlcompare_dataset_dataset_998aa249_new_20260104_025829_b28946b5
+🔎 To review the diff, run: sqlcompare inspect compare_sqlcompare_dataset_dataset_998aa249_previous_sqlcompare_dataset_dataset_998aa249_new_20260104_025829_b28946b5
 💡 Tips: --stats for per-column counts, --missing-current/--missing-previous for row-only, --column <name> to filter, --list-columns to inspect available fields.
 ```

examples/stats_compare.md

@@ -5,7 +5,7 @@ Compare statistics between two CSV files
 ## Command
 
 ```bash
-sqlcompare table tests/datasets/stats_compare/previous.csv tests/datasets/stats_compare/current.csv --stats
+sqlcompare stats tests/datasets/stats_compare/previous.csv tests/datasets/stats_compare/current.csv
 ```
 
 ## Output

sqlcompare/cli.py

@@ -2,17 +2,19 @@
 
 import typer
 
-from sqlcompare.analyze_diff import analyze_diff_cmd
 from sqlcompare.dataset import dataset_cmd
+from sqlcompare.inspect import inspect_cmd
 from sqlcompare.list_diffs import list_diffs_cmd
 from sqlcompare.query import query_cmd
+from sqlcompare.stats import stats_cmd
 from sqlcompare.table import table_cmd
 
 app = typer.Typer(help="Compare database tables and inspect diffs.")
 
 # Register all commands
 app.command("table")(table_cmd)
-app.command("analyze-diff")(analyze_diff_cmd)
+app.command("inspect")(inspect_cmd)
+app.command("stats")(stats_cmd)
 app.command("list-diffs")(list_diffs_cmd)
 app.command("query")(query_cmd)
 app.command("dataset")(dataset_cmd)

sqlcompare/compare/comparator.py

@@ -372,6 +372,6 @@ def compare(
         save_test_runs(runs)
 
         log.debug(f"\U0001f4c1 Analysis data saved with ID: {diff_id}")
-        log.debug(f"Use 'sqlcompare analyze-diff {diff_id}' to review differences")
+        log.debug(f"Use 'sqlcompare inspect {diff_id}' to review differences")
 
         return diff_id

sqlcompare/dataset.py

@@ -133,5 +133,50 @@ def dataset_cmd(
         None, "--schema", help="Schema for dataset tables"
     ),
 ) -> None:
-    """Compare datasets defined in YAML configuration file."""
+    """Compare datasets defined in YAML configuration.
+
+    Supports comparing:
+    - SQL queries (select_sql)
+    - CSV/XLSX files (file_name)
+    - Mix of both
+
+    YAML Format:
+        previous:
+          select_sql: "SELECT * FROM users WHERE created < '2024-01-01'"
+          index:
+            - user_id
+
+        new:
+          select_sql: "SELECT * FROM users WHERE created >= '2024-01-01'"
+          index:
+            - user_id
+
+        # Or with files
+        previous:
+          file_name: "{{here}}/previous.csv"
+          index:
+            - customer_id
+            - order_id
+
+        new:
+          file_name: "{{here}}/current.xlsx"
+          index:
+            - customer_id
+            - order_id
+
+    Examples:
+        # Compare using dataset config
+        sqlcompare dataset configs/migration_check.yaml
+
+        # Override connection from YAML
+        sqlcompare dataset configs/validation.yaml -c snowflake_prod
+
+        # Use {{here}} in YAML for relative file paths
+        # {{here}} expands to the directory containing the YAML file
+
+    Notes:
+        - index columns must match between previous and new
+        - Both sides must use the same connection (or files)
+        - Use 'conn' or 'connection' key in YAML to specify database
+    """
     compare_dataset(path, connection, schema)

sqlcompare/analyze_diff.py sqlcompare/inspect.pysqlcompare/analyze_diff.py renamed to sqlcompare/inspect.py

@@ -15,7 +15,7 @@
 from sqlcompare.log import log
 
 
-def analyze_diff(
+def inspect_diff(
     diff_id: str,
     column: str | None = None,
     limit: int = 25,
@@ -26,7 +26,7 @@ def analyze_diff(
     missing_previous: bool = False,
 ) -> None:
     """
-    Analyze diff results from a previous comparison run.
+    Inspect diff results from a previous comparison run.
 
     Supports database-backed diffs and legacy pickle files.
     """
@@ -201,7 +201,7 @@ def analyze_diff(
     log.error("❌ Pickle-based diff files are not supported without pandas.")
 
 
-def analyze_diff_cmd(
+def inspect_cmd(
     diff_id: str = typer.Argument(..., help="Diff run ID"),
     column: str | None = typer.Option(
         None, "--column", "-c", help="Filter by specific column name"
@@ -223,8 +223,35 @@ def analyze_diff_cmd(
         False, "--missing-previous", help="Show rows only in previous dataset"
     ),
 ) -> None:
-    """Analyze diff results from a previous comparison run."""
-    analyze_diff(
+    """Inspect results from a previous comparison.
+
+    After running 'table' or 'dataset' comparison, use this command to analyze
+    the saved diff results. You can view statistics, filter by column, examine
+    missing rows, or export results.
+
+    Examples:
+        # View diff summary with statistics
+        sqlcompare inspect <diff_id> --stats
+
+        # Filter differences for specific column
+        sqlcompare inspect <diff_id> --column revenue
+
+        # Show rows only in current dataset
+        sqlcompare inspect <diff_id> --missing-current
+
+        # Show rows only in previous dataset
+        sqlcompare inspect <diff_id> --missing-previous
+
+        # List all available columns
+        sqlcompare inspect <diff_id> --list-columns
+
+        # Show more results
+        sqlcompare inspect <diff_id> --limit 100
+
+        # Save filtered results to CSV
+        sqlcompare inspect <diff_id> --column price --save
+    """
+    inspect_diff(
         diff_id,
         column=column,
         limit=limit,

sqlcompare/list_diffs.py

@@ -62,5 +62,21 @@ def list_diffs_cmd(
     pattern: str | None = typer.Argument(None, help="Match diff IDs"),
     test: str | None = typer.Option(None, "--test", help="Filter by test name"),
 ) -> None:
-    """List all available diff data files."""
+    """List all saved comparison results.
+
+    Shows all diff IDs from previous table/dataset comparisons, sorted by date.
+
+    Examples:
+        # List all diffs
+        sqlcompare list-diffs
+
+        # Filter by pattern
+        sqlcompare list-diffs users
+
+        # Filter by test name
+        sqlcompare list-diffs --test migration_check
+
+    Output:
+        Displays: diff_id, test name, file size, creation date
+    """
     list_diffs(pattern, test)

sqlcompare/query.py

@@ -57,7 +57,7 @@ def query(q: str, connection: str | None, output: str) -> None:
 def query_cmd(
     q: str = typer.Argument(..., help="SQL query to run"),
     connection: str | None = typer.Option(
-        None, "--connection", "-c", "--conn", help="Connector name"
+        None, "--connection", "-c", help="Database connector name"
     ),
     output: str = typer.Option(
         "terminal",
@@ -66,5 +66,28 @@ def query_cmd(
         help="Output format or file path. Use 'terminal' or provide a .csv filename",
     ),
 ) -> None:
-    """Execute SQL query and display or save results."""
+    """Execute SQL query and display or save results.
+
+    Examples:
+        # Display in terminal
+        sqlcompare query "SELECT * FROM users LIMIT 10"
+
+        # Save to CSV
+        sqlcompare query "SELECT id, name FROM customers" --output results.csv
+
+        # Use specific connection
+        sqlcompare query "SELECT COUNT(*) FROM orders" -c snowflake_prod
+
+        # Multi-line query
+        sqlcompare query "
+            SELECT u.id, u.name, COUNT(o.id) as order_count
+            FROM users u
+            LEFT JOIN orders o ON u.id = o.user_id
+            GROUP BY u.id, u.name
+        " -c postgres_dev --output user_orders.csv
+
+    Output Options:
+        --output terminal: Display in terminal (default)
+        --output file.csv: Save to CSV file
+    """
     query(q, connection, output)

sqlcompare/stats.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import typer
+
+from sqlcompare.utils.test_types.stats import compare_table_stats
+
+
+def stats_cmd(
+    table1: str = typer.Argument(..., help="Previous table name or CSV/XLSX file path"),
+    table2: str = typer.Argument(..., help="Current table name or CSV/XLSX file path"),
+    connection: str | None = typer.Option(
+        None, "--connection", "-c", help="Database connector name"
+    ),
+) -> None:
+    """Compare table statistics without row-by-row comparison.
+
+    Displays column-level statistics including:
+    - Row counts
+    - Null counts
+    - Distinct value counts
+    - Differences between previous and current
+
+    This is useful for:
+    - Quick data quality checks
+    - Schema validation
+    - High-level change detection
+    - Large tables where row comparison would be slow
+
+    Examples:
+        # Compare table statistics
+        sqlcompare stats analytics.users analytics.users_new
+
+        # Compare CSV file statistics
+        sqlcompare stats exports/jan.csv exports/feb.csv
+
+        # Compare with specific connection
+        sqlcompare stats orders_v1 orders_v2 -c postgres_prod
+
+    Output Columns:
+        PREV_ROWS, NEW_ROWS: Total row counts
+        PREV_NULLS, NEW_NULLS: Null counts per column
+        PREV_DISTINCT, NEW_DISTINCT: Unique value counts
+        *_DIFF: Calculated differences
+    """
+    compare_table_stats(table1, table2, connection)