Add catalog CLI commands to vgi-client

Expose catalog API via CLI subcommands:
- catalog list/attach/detach/create/drop/version
- schema list/get/create/drop/contents
- table get/create/drop/rename/comment/scan-function + column ops
- view get/create/drop/rename/comment
- transaction begin/commit/rollback

Refactored cli.py from @click.command to @click.group with
invoke_without_command=True to preserve backward-compatible
function invocation (--function) while adding subcommands.

Added transaction methods and TransactionBeginResult to
CatalogClientMixin for transaction support.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rustyconover

tests/client/test_cli.py

@@ -259,11 +259,13 @@ def test_invalid_attach_id_hex(self, example_worker: str) -> None:
         assert result.exit_code != 0
         assert "valid hex string" in result.output
 
-    def test_missing_required_function(self) -> None:
-        """--function is required."""
+    def test_missing_function_shows_help(self) -> None:
+        """Calling CLI with no arguments shows help (group behavior)."""
         runner = CliRunner()
         result = runner.invoke(cli, [])
-        assert result.exit_code != 0
+        # With Click group, no subcommand and no --function shows help
+        assert result.exit_code == 0
+        assert "Usage:" in result.output
 
 
 class TestCLITableFunction:

vgi/client/catalog_mixin.py

@@ -18,6 +18,7 @@ class CatalogEnabledClient(CatalogClientMixin, Client):
 import io
 import subprocess
 from collections.abc import Iterator
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, cast
 
 import pyarrow as pa
@@ -43,6 +44,21 @@ class CatalogEnabledClient(CatalogClientMixin, Client):
     import structlog.stdlib
 
 
+@dataclass
+class TransactionBeginResult:
+    """Result of beginning a transaction."""
+
+    transaction_id: TransactionId
+
+    @staticmethod
+    def deserialize(batch: pa.RecordBatch) -> "TransactionBeginResult":
+        """Deserialize from an Arrow record batch."""
+        row = batch.to_pydict()
+        return TransactionBeginResult(
+            transaction_id=TransactionId(bytes(row["transaction_id"][0])),
+        )
+
+
 class CatalogClientError(Exception):
     """Error raised by catalog operations."""
 
@@ -1168,3 +1184,67 @@ def view_comment_set(
             comment=comment,
             ignore_not_found=ignore_not_found,
         )
+
+    # =========================================================================
+    # Transaction Methods
+    # =========================================================================
+
+    def transaction_begin(
+        self,
+        *,
+        attach_id: AttachId,
+    ) -> TransactionBeginResult:
+        """Begin a new transaction.
+
+        Args:
+            attach_id: The attachment ID from catalog_attach.
+
+        Returns:
+            TransactionBeginResult containing the transaction_id.
+
+        """
+        result = self._catalog_invoke(
+            "catalog_transaction_begin",
+            attach_id=attach_id,
+        )
+        if result is None:
+            raise CatalogClientError("transaction_begin returned no result")
+        return TransactionBeginResult.deserialize(result)
+
+    def transaction_commit(
+        self,
+        *,
+        attach_id: AttachId,
+        transaction_id: TransactionId,
+    ) -> None:
+        """Commit a transaction.
+
+        Args:
+            attach_id: The attachment ID from catalog_attach.
+            transaction_id: The transaction ID from transaction_begin.
+
+        """
+        self._catalog_invoke(
+            "catalog_transaction_commit",
+            attach_id=attach_id,
+            transaction_id=transaction_id,
+        )
+
+    def transaction_rollback(
+        self,
+        *,
+        attach_id: AttachId,
+        transaction_id: TransactionId,
+    ) -> None:
+        """Rollback a transaction.
+
+        Args:
+            attach_id: The attachment ID from catalog_attach.
+            transaction_id: The transaction ID from transaction_begin.
+
+        """
+        self._catalog_invoke(
+            "catalog_transaction_rollback",
+            attach_id=attach_id,
+            transaction_id=transaction_id,
+        )

vgi/client/cli.py

@@ -1,6 +1,7 @@
 r"""Command-line interface for the VGI client.
 
-This module provides the CLI entry point for invoking VGI functions.
+This module provides the CLI entry point for invoking VGI functions and
+managing catalogs.
 
 Usage:
     # Table-in-out functions (with input):
@@ -20,6 +21,12 @@
     vgi-client --input data.parquet --function transform --args '["prefix"]' \
         --table-input-position 1
 
+    # Catalog operations:
+    vgi-client catalog list --server vgi-example-catalog-worker
+    vgi-client catalog attach memory --server vgi-example-catalog-worker
+    vgi-client schema list $ATTACH_ID --server vgi-example-catalog-worker
+    vgi-client table get $ATTACH_ID main users --server vgi-example-catalog-worker
+
 """
 
 import io
@@ -121,11 +128,17 @@ def close(self) -> None:
 
 
 def _create_cli() -> Any:
-    """Create the CLI command. Separated for testability."""
+    """Create the CLI command group. Separated for testability."""
     import click
     import pyarrow.parquet as pq
 
-    @click.command()
+    from vgi.client.cli_catalog import catalog
+    from vgi.client.cli_schema import schema
+    from vgi.client.cli_table import table
+    from vgi.client.cli_transaction import transaction
+    from vgi.client.cli_view import view
+
+    @click.group(invoke_without_command=True)
     @click.option(
         "--input",
         "input_file",
@@ -150,7 +163,7 @@ def _create_cli() -> Any:
     @click.option(
         "--function",
         "function_name",
-        required=True,
+        required=False,
         type=str,
         help="Name of the function to run (e.g., echo, sum_all_columns, repeat_inputs)",
     )
@@ -221,11 +234,13 @@ def _create_cli() -> Any:
             "otherwise table. Use 'scalar' for scalar functions."
         ),
     )
+    @click.pass_context
     def cli(
+        ctx: click.Context,
         input_file: str | None,
         output_file: str | None,
         output_format: str,
-        function_name: str,
+        function_name: str | None,
         arguments: str,
         server_path: str,
         worker_stderr: bool,
@@ -235,7 +250,21 @@ def cli(
         attach_id: str | None,
         function_type: str,
     ) -> None:
-        """Invoke a VGI function and display results."""
+        """VGI client for function invocation and catalog management.
+
+        When called without a subcommand and with --function, invokes a VGI function.
+        Use subcommands (catalog, schema, table, view, transaction) for catalog ops.
+
+        """
+        # If a subcommand is being invoked, skip function invocation
+        if ctx.invoked_subcommand is not None:
+            return
+
+        # Legacy function invocation mode - requires --function
+        if function_name is None:
+            click.echo(ctx.get_help())
+            return
+
         try:
             args_list = json.loads(arguments)
             if not isinstance(args_list, list):
@@ -361,6 +390,13 @@ def cli(
             if output_writer is not None:
                 output_writer.close()
 
+    # Add catalog subcommand groups
+    cli.add_command(catalog)
+    cli.add_command(schema)
+    cli.add_command(table)
+    cli.add_command(view)
+    cli.add_command(transaction)
+
     return cli
 
 

vgi/client/cli_catalog.py

@@ -0,0 +1,129 @@
+"""Catalog CLI commands for VGI.
+
+This module provides CLI commands for catalog operations:
+- list: List available catalogs
+- attach: Attach to a catalog
+- detach: Detach from a catalog
+- create: Create a new catalog
+- drop: Drop a catalog
+- version: Get catalog version
+
+"""
+
+from __future__ import annotations
+
+import click
+
+from vgi.catalog import OnConflict
+from vgi.client.client import Client
+from vgi.client.cli_utils import (
+    catalog_attach_result_to_dict,
+    hex_to_attach_id,
+    hex_to_transaction_id,
+    output_json,
+    parse_json_option,
+)
+
+
+@click.group()
+def catalog() -> None:
+    """Manage catalogs."""
+
+
+@catalog.command("list")
+@click.option("--server", required=True, help="VGI worker command")
+def catalog_list(server: str) -> None:
+    """List available catalogs."""
+    client = Client(server)
+    catalogs = client.catalogs()
+    output_json(catalogs)
+
+
+@catalog.command("attach")
+@click.argument("name")
+@click.option("--server", required=True, help="VGI worker command")
+@click.option("--options", default="{}", help="Catalog options as JSON object")
+def catalog_attach(name: str, server: str, options: str) -> None:
+    """Attach to a catalog and return attach_id.
+
+    NAME is the catalog name to attach to.
+
+    """
+    opts = parse_json_option(options, "--options")
+    client = Client(server)
+    result = client.catalog_attach(name=name, options=opts)
+    output_json(catalog_attach_result_to_dict(result))
+
+
+@catalog.command("detach")
+@click.argument("attach_id")
+@click.option("--server", required=True, help="VGI worker command")
+def catalog_detach(attach_id: str, server: str) -> None:
+    """Detach from a catalog.
+
+    ATTACH_ID is the hex-encoded attach ID from catalog attach.
+
+    """
+    client = Client(server)
+    client.catalog_detach(attach_id=hex_to_attach_id(attach_id))
+    output_json({"status": "detached"})
+
+
+@catalog.command("create")
+@click.argument("name")
+@click.option("--server", required=True, help="VGI worker command")
+@click.option(
+    "--on-conflict",
+    type=click.Choice(["error", "ignore", "replace"]),
+    default="error",
+    help="Behavior if catalog already exists",
+)
+@click.option("--options", default="{}", help="Catalog options as JSON object")
+def catalog_create(name: str, server: str, on_conflict: str, options: str) -> None:
+    """Create a new catalog.
+
+    NAME is the name for the new catalog.
+
+    """
+    opts = parse_json_option(options, "--options")
+    client = Client(server)
+    client.catalog_create(
+        name=name,
+        on_conflict=OnConflict(on_conflict),
+        options=opts,
+    )
+    output_json({"status": "created", "name": name})
+
+
+@catalog.command("drop")
+@click.argument("name")
+@click.option("--server", required=True, help="VGI worker command")
+def catalog_drop(name: str, server: str) -> None:
+    """Drop a catalog.
+
+    NAME is the name of the catalog to drop.
+
+    """
+    client = Client(server)
+    client.catalog_drop(name=name)
+    output_json({"status": "dropped", "name": name})
+
+
+@catalog.command("version")
+@click.argument("attach_id")
+@click.option("--server", required=True, help="VGI worker command")
+@click.option("--transaction-id", help="Transaction ID (hex) for transactional read")
+def catalog_version(attach_id: str, server: str, transaction_id: str | None) -> None:
+    """Get the current catalog version.
+
+    ATTACH_ID is the hex-encoded attach ID from catalog attach.
+
+    """
+    client = Client(server)
+    version = client.catalog_version(
+        attach_id=hex_to_attach_id(attach_id),
+        transaction_id=(
+            hex_to_transaction_id(transaction_id) if transaction_id else None
+        ),
+    )
+    output_json({"version": version, "attach_id": attach_id})