@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/cli.py

@@ -0,0 +1,2532 @@
+"""Typer CLI wrapper for Confluence operations during the native Python implementations."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import structlog
+import typer
+
+from .config import ConfluenceSettings, load_settings
+from .content import ContentClient
+from .content_v2 import ContentClientV2
+from .errors import ConfluenceClientError
+from .eventing import Poller
+from .http import ConfluenceClient
+from .orchestration import BatchRunner, WebhookClient
+from .reporting import RunSummary, write_reports
+
+# ---------------------------------------------------------------------------
+# Typer setup & logging
+# ---------------------------------------------------------------------------
+
+app = typer.Typer(add_completion=False, help="Confluence operations orchestrator")
+content_app = typer.Typer(help="Native Confluence API commands")
+batch_app = typer.Typer(help="Batch polling utilities (REST v1)")
+webhook_app = typer.Typer(help="Webhook management (REST v1)")
+app.add_typer(content_app, name="content")
+app.add_typer(batch_app, name="batch-native")
+app.add_typer(webhook_app, name="webhook-native")
+
+# Logger will be configured in main() callback
+logger = logging.getLogger("confluence_cli")
+
+# ---------------------------------------------------------------------------
+# Paths and legacy script mapping
+# ---------------------------------------------------------------------------
+
+_SCRIPTS_DIR = Path(__file__).resolve().parents[3]
+_DEFAULT_REPORT_DIR = (_SCRIPTS_DIR / "reports" / "confluence_runs").resolve()
+
+
+@dataclass(slots=True)
+class CLIContext:
+    report_dir: Path
+    markdown: bool
+    api_version: str
+    reports: bool
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def _normalise_server(server: str | None, settings: ConfluenceSettings) -> str:
+    return server.lower() if server else settings.default_server.lower()
+
+
+def _build_env(server: str, settings: ConfluenceSettings) -> dict:
+    token = settings.token_for(server)
+    if not token:
+        raise ConfluenceClientError(
+            f"Token for server '{server}' is missing. Run 'uv run --project vds_cli vds-cli env load'.",
+            context={"server": server},
+        )
+    env = os.environ.copy()
+    env.update(
+        {
+            "CONFLUENCE_SERVER": server,
+            "CONFLUENCE_TOKEN": token,
+            "CONFLUENCE_URL": str(settings.url_for(server)),
+            "INTERNAL_CONFLUENCE_TOKEN": settings.internal_token or "",
+            "EXTERNAL_CONFLUENCE_TOKEN": settings.external_token or "",
+        }
+    )
+    return env
+
+
+def _build_http_client(settings: ConfluenceSettings, server: str) -> ConfluenceClient:
+    return ConfluenceClient(settings, server=server)
+
+
+def _get_cli_ctx(ctx: typer.Context) -> CLIContext:
+    cli_ctx = ctx.obj
+    if not isinstance(cli_ctx, CLIContext):
+        raise RuntimeError("CLI context not initialised")
+    return cli_ctx
+
+
+def _ensure_v1_api(ctx: typer.Context, command: str) -> None:
+    """Legacy command guard - redirects to native implementations."""
+    settings = load_settings(strict=False)
+    if settings is None:
+        typer.echo("Error: configuration not found", err=True)
+        raise typer.Exit(code=1) from None
+
+
+def _build_content_client(
+    settings: ConfluenceSettings,
+    server: str,
+    api_version: str,
+):
+    http_client = _build_http_client(settings, server)
+    if not http_client.supports_api_version(api_version):
+        raise ConfluenceClientError(
+            f"API version '{api_version}' is not supported for server '{server}'.",
+            context={"server": server, "api_version": api_version},
+        )
+    if api_version == "v1":
+        return ContentClient(http_client)
+    if api_version == "v2":
+        return ContentClientV2(http_client)
+    raise ConfluenceClientError(f"Unsupported API version '{api_version}'")
+
+
+def _record_summary(
+    ctx: typer.Context,
+    *,
+    command: str,
+    args: list[str],
+    server: str,
+    exit_code: int,
+    started_at: datetime,
+    finished_at: datetime,
+) -> None:
+    cli_ctx = _get_cli_ctx(ctx)
+    summary = RunSummary(
+        command=command,
+        args=args,
+        server=server,
+        exit_code=exit_code,
+        duration_ms=int((finished_at - started_at).total_seconds() * 1000),
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+    if cli_ctx.reports:
+        write_reports(summary, base_dir=cli_ctx.report_dir, include_markdown=cli_ctx.markdown)
+
+
+def _emit_json(payload: object) -> None:
+    text = json.dumps(payload, indent=2, sort_keys=True)
+    if sys.stdout.isatty():
+        typer.echo(text)
+    else:
+        sys.stdout.write(text + "\n")
+
+
+def _expand_option(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _content_summary_args(
+    *, cql: str | None = None, limit: int | None = None, start: int | None = None, space: str | None = None
+) -> list[str]:
+    parts: list[str] = []
+    if cql is not None:
+        parts.append(cql)
+    if limit is not None:
+        parts.append(f"limit={limit}")
+    if start is not None:
+        parts.append(f"start={start}")
+    if space is not None:
+        parts.append(f"space={space}")
+    return parts
+
+
+def _read_text_file(path: Path) -> str:
+    if not path.exists():
+        raise typer.BadParameter(f"File not found: {path}")
+    if path.is_dir():
+        raise typer.BadParameter(f"Expected file but found directory: {path}")
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise typer.BadParameter(f"Unable to read file {path}: {exc}") from exc
+
+
+def _parse_json_option(value: str | None, option_name: str) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON for {option_name}: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter(f"{option_name} must decode to a JSON object")
+    return parsed
+
+
+def _parent_context(ctx: typer.Context) -> typer.Context:
+    return ctx.parent or ctx
+
+
+# ---------------------------------------------------------------------------
+# Typer callbacks & native commands
+# ---------------------------------------------------------------------------
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    report_dir: Path | None = typer.Option(None, help=f"Directory for run reports (default: {_DEFAULT_REPORT_DIR})"),
+    markdown: bool = typer.Option(True, help="Emit Markdown summaries alongside JSON reports"),
+    reports: bool = typer.Option(True, "--reports/--no-reports", help="Persist run reports to disk"),
+    json_only: bool = typer.Option(
+        False,
+        "--json-only",
+        help="Emit JSON to stdout only (disables reports and markdown)",
+    ),
+    api_version: str = typer.Option("v1", "--api-version", "-A", help="Select REST API version (v1 or v2)"),
+    structured_logs: bool = typer.Option(
+        False, "--structured-logs/--no-structured-logs", help="Emit structured JSON logs to stderr"
+    ),
+) -> None:
+    resolved = report_dir.resolve() if report_dir else _DEFAULT_REPORT_DIR
+    version = api_version.lower()
+    if version not in {"v1", "v2"}:
+        raise typer.BadParameter("api-version must be one of: v1, v2")
+    if json_only:
+        markdown = False
+        reports = False
+
+    # Configure logging/structlog
+    if structured_logs:
+        structlog.configure(
+            processors=[
+                structlog.processors.TimeStamper(fmt="iso"),
+                structlog.stdlib.add_log_level,
+                structlog.processors.StackInfoRenderer(),
+                structlog.processors.format_exc_info,
+                structlog.processors.JSONRenderer(),
+            ],
+            logger_factory=structlog.stdlib.LoggerFactory(),
+            wrapper_class=structlog.stdlib.BoundLogger,
+            cache_logger_on_first_use=True,
+        )
+        global logger  # noqa: PLW0603
+        logger = structlog.get_logger("confluence_cli")  # type: ignore[assignment]
+    else:
+        if json_only:
+            logging.basicConfig(level=logging.CRITICAL, stream=sys.stderr)
+            structlog.configure(wrapper_class=structlog.make_filtering_bound_logger(logging.CRITICAL))
+        else:
+            logging.basicConfig(level=logging.INFO, stream=sys.stderr, format="%(levelname)s %(name)s: %(message)s")
+
+    ctx.obj = CLIContext(report_dir=resolved, markdown=markdown, api_version=version, reports=reports)
+
+
+@app.command("templates")
+def cmd_templates(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None, help="Additional arguments for template operations", show_default=False, metavar="ARGS"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Number of templates to list"),
+    space_key: str | None = typer.Option(None, "--space", "-k", help="Space key filter"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Native Python template management"""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
+
+        # Use native Python implementation
+        if hasattr(client, "list_templates"):
+            result = client.list_templates(space_key=space_key)
+        else:
+            result = {"templates": [], "message": "Templates API not available for this server"}
+
+        if json_output:
+            _emit_json(result)
+        else:
+            templates_payload = []
+            if isinstance(result, dict):
+                templates_payload = (
+                    result.get("blueprints")
+                    or result.get("templates")
+                    or result.get("results")
+                    or result.get("contentTemplates")
+                    or []
+                )
+            elif isinstance(result, list):
+                templates_payload = result
+
+            count = len(templates_payload)
+            typer.echo(f"Found {count} templates:")
+            for template in templates_payload[:limit]:
+                if isinstance(template, dict):
+                    name = template.get("name", "Unknown")
+                    template_id = template.get("templateId") or template.get("id") or template.get("uuid") or "Unknown"
+                else:
+                    name = str(template)
+                    template_id = "Unknown"
+                typer.echo(f"  - {name} (ID: {template_id})")
+
+        exit_code = 0
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="templates",
+            args=args or [],
+            server=server_key,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+    except Exception as exc:
+        logger.error("templates_command_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+@app.command("batch")
+def cmd_batch(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None, help="Use 'confluence content batch --help' for available subcommands", show_default=False, metavar="ARGS"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    """Legacy batch command - use 'confluence content batch' subcommands instead."""
+    typer.echo("Error: The 'batch' command is deprecated. Use 'confluence content batch' subcommands:", err=True)
+    typer.echo("  confluence content batch scan --cql '<query>' [options]", err=True)
+    typer.echo("  confluence content batch snapshot --cql '<query>' [options]", err=True)
+    raise typer.Exit(code=1) from None
+
+
+@app.command("webhooks")
+def cmd_webhooks(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None, help="Additional arguments for webhook operations", show_default=False, metavar="ARGS"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    list_webhooks: bool = typer.Option(False, "--list", "-l", help="List existing webhooks"),
+    create_name: str | None = typer.Option(None, "--name", "-n", help="Webhook name"),
+    create_url: str | None = typer.Option(None, "--url", "-u", help="Webhook URL"),
+    create_event: str | None = typer.Option(None, "--event", "-e", help="Event type"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Native Python webhook management"""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        webhook_client = WebhookClient(_build_http_client(settings, server_key))
+
+        if list_webhooks or (not create_name and not create_url and not create_event):
+            # List webhooks
+            result = webhook_client.list()
+            if json_output or not sys.stdout.isatty():
+                _emit_json(result)
+            else:
+                webhooks = result.get("webhooks", [])
+                count = len(webhooks)
+                typer.echo(f"Found {count} webhooks:")
+                for webhook in webhooks:
+                    name = webhook.get("name", "Unknown")
+                    url = webhook.get("url", "Unknown")
+                    events = webhook.get("events", [])
+                    typer.echo(f"  - {name}: {url} (events: {', '.join(events)})")
+
+        elif create_name and create_url and create_event:
+            # Create webhook
+            result = webhook_client.create(name=create_name, url=create_url, events=[create_event])
+            if json_output or not sys.stdout.isatty():
+                _emit_json(result)
+            else:
+                webhook_id = result.get("id", "Unknown")
+                typer.echo(f"Created webhook '{create_name}' with ID: {webhook_id}")
+
+        else:
+            typer.echo(
+                "Error: Either use --list to list webhooks or provide --name, --url, and --event to create", err=True
+            )
+            raise typer.Exit(code=1) from None
+
+        exit_code = 0
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="webhooks",
+            args=args or [],
+            server=server_key,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+    except Exception as exc:
+        logger.error("webhooks_command_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+@app.command("search")
+def cmd_search(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None, help="Additional arguments for CQL search", show_default=False, metavar="ARGS"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
+    limit: int = typer.Option(25, "--limit", "-l", help="Number of results"),
+    start: int = typer.Option(0, "--start", help="Pagination start"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    excerpt: str | None = typer.Option(None, "--excerpt", help="Excerpt strategy (e.g., 'highlighted', 'indexed')"),
+    advanced: bool = typer.Option(False, "--advanced", help="Use advanced CQL search with additional options"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Native Python CQL search. Use --advanced for additional options like excerpt."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
+
+        # Use native Python implementation
+        expand_list = _expand_option(expand) if expand else None
+        if advanced or excerpt:
+            result = client.cql_advanced(cql, limit=limit, start=start, expand=expand_list, excerpt=excerpt)
+        else:
+            result = client.search_cql(cql, limit=limit, start=start, expand=expand_list)
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result)
+        else:
+            results = result.get("results", [])
+            count = len(results)
+            total = result.get("size", 0)
+            typer.echo(f"Found {count} of {total} results for CQL: {cql}")
+            for item in results:
+                title = item.get("title", "Unknown")
+                page_id = item.get("id", "Unknown")
+                space = item.get("space", {}).get("key", "Unknown")
+                typer.echo(f"  - {title} (ID: {page_id}, Space: {space})")
+
+        exit_code = 0
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="search",
+            args=args or [],
+            server=server_key,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+    except Exception as exc:
+        logger.error("search_command_failed: %s", exc)
+
+
+@app.command("search-by-space-type")
+def cmd_search_by_space_type(
+    ctx: typer.Context,
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    space_key: str | None = typer.Option(None, "--space", help="Space key to filter by"),
+    content_type: str | None = typer.Option(
+        None, "--type", help="Content type (e.g., 'page', 'blogpost', 'comment')"
+    ),
+    limit: int = typer.Option(25, "--limit", "-l", help="Number of results"),
+    start: int = typer.Option(0, "--start", help="Pagination start"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Search by space and/or content type (helper that builds CQL automatically)."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+
+    try:
+        if not space_key and not content_type:
+            raise typer.BadParameter("At least one of --space or --type must be provided")
+
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
+
+        expand_list = _expand_option(expand) if expand else None
+        result = client.search_by_space_and_type(
+            space_key=space_key,
+            content_type=content_type,
+            limit=limit,
+            start=start,
+            expand=expand_list,
+        )
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result)
+        else:
+            results = result.get("results", [])
+            count = len(results)
+            total = result.get("size", 0)
+            typer.echo(f"Found {count} of {total} results")
+            for item in results:
+                title = item.get("title", "Unknown")
+                page_id = item.get("id", "Unknown")
+                space = item.get("space", {}).get("key", "Unknown")
+                item_type = item.get("type", "Unknown")
+                typer.echo(f"  - {title} (ID: {page_id}, Space: {space}, Type: {item_type})")
+
+        exit_code = 0
+    except (typer.BadParameter, Exception) as exc:
+        exit_code = 1
+        logger.error("search_by_space_type_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        args_list: list[str] = []
+        if space_key:
+            args_list.append(f"space={space_key}")
+        if content_type:
+            args_list.append(f"type={content_type}")
+        _record_summary(
+            parent_ctx,
+            command="search-by-space-type",
+            args=args_list,
+            server=server_key if "server_key" in locals() else "internal",
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("attachments")
+def cmd_attachments(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None, help="Additional arguments for attachment operations", show_default=False, metavar="ARGS"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    page_id: str | None = typer.Option(None, "--page", "-p", help="Page ID for attachments"),
+    list_attachments: bool = typer.Option(False, "--list", "-l", help="List attachments for page"),
+    upload_file: str | None = typer.Option(None, "--upload", "-f", help="File to upload"),
+    comment: str | None = typer.Option(None, "--comment", "-c", help="Upload comment"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Native Python attachment management"""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
+
+        if list_attachments or (page_id and not upload_file):
+            # List attachments
+            if not page_id:
+                typer.echo("Error: --page ID required for listing attachments", err=True)
+                raise typer.Exit(code=1) from None
+
+            result = client.list_attachments(page_id)
+            if json_output or not sys.stdout.isatty():
+                _emit_json(result)
+            else:
+                attachments = result.get("results", [])
+                count = len(attachments)
+                typer.echo(f"Found {count} attachments for page {page_id}:")
+                for attachment in attachments:
+                    name = attachment.get("title", "Unknown")
+                    size = attachment.get("size", 0)
+                    typer.echo(f"  - {name} ({size} bytes)")
+
+        elif upload_file and page_id:
+            # Upload attachment
+            file_path = Path(upload_file)
+            if not file_path.exists():
+                typer.echo(f"Error: File not found: {upload_file}", err=True)
+                raise typer.Exit(code=1) from None
+
+            result = client.upload_attachment(page_id, file_path, comment=comment)
+            if json_output or not sys.stdout.isatty():
+                _emit_json(result)
+            else:
+                attachment_id = result.get("id", "Unknown")
+                typer.echo(f"Uploaded attachment '{file_path.name}' with ID: {attachment_id}")
+
+        else:
+            typer.echo("Error: Either use --list with --page or provide --page and --upload", err=True)
+            raise typer.Exit(code=1) from None
+
+        exit_code = 0
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="attachments",
+            args=args or [],
+            server=server_key,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+    except Exception as exc:
+        logger.error("attachments_command_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+@app.command("space-permissions")
+def cmd_space_permissions(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: get, set, remove"),
+    space_key: str = typer.Option(..., "--space-key", "-k", help="Confluence space key"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    user_key: str | None = typer.Option(None, "--user", "-u", help="User key for user-targeted operations"),
+    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name for group-targeted operations"),
+    anonymous: bool = typer.Option(False, "--anonymous", help="Target anonymous permissions"),
+    operations: list[str] = typer.Option(
+        [],
+        "--operation",
+        "-o",
+        help="Space permission operation key (repeatable, e.g., administer, read)",
+    ),
+    permissions_file: Path | None = typer.Option(
+        None,
+        "--permissions-file",
+        help="JSON file with bulk permission definitions (uses set_permissions_to_multiple_items_for_space)",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence space permissions."""
+
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        resolved_operations = operations or None
+        args_summary = [
+            action,
+            f"space={space_key}",
+            f"user={user_key}",
+            f"group={group_name}",
+            f"anonymous={anonymous}",
+            f"operations={operations}",
+            f"permissions_file={permissions_file}",
+        ]
+
+        if action == "get":
+            result = client.get_space_permissions(space_key)
+            result_payload = {"space": space_key, "permissions": result}
+
+        elif action == "set":
+            if not yes:
+                raise typer.BadParameter("--yes required for write operations")
+
+            targets = [bool(user_key), bool(group_name), anonymous, bool(permissions_file)]
+            if sum(1 for flag in targets if flag) != 1:
+                raise typer.BadParameter(
+                    "Provide exactly one of --user, --group, --anonymous, or --permissions-file for set action"
+                )
+
+            if permissions_file:
+                file_content = _read_text_file(permissions_file)
+                try:
+                    parsed = json.loads(file_content)
+                except json.JSONDecodeError as exc:
+                    raise typer.BadParameter(f"Invalid JSON in permissions file: {exc}") from exc
+
+                if isinstance(parsed, dict):
+                    items: list[dict[str, Any]] = [parsed]
+                elif isinstance(parsed, list):
+                    if not all(isinstance(item, dict) for item in parsed):
+                        raise typer.BadParameter("--permissions-file list entries must be JSON objects")
+                    items = parsed  # type: ignore[assignment]
+                else:
+                    raise typer.BadParameter("--permissions-file must contain a JSON object or array")
+
+                result = client.set_permissions_to_multiple_items_for_space(space_key, items)
+                result_payload = {"space": space_key, "bulk": True, "items_processed": len(items), "result": result}
+
+            elif user_key:
+                if not resolved_operations:
+                    raise typer.BadParameter("At least one --operation required when setting user permissions")
+                result = client.set_permissions_to_user_for_space(
+                    space_key,
+                    user_key,
+                    operations=resolved_operations,
+                )
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "user", "key": user_key},
+                    "operations": resolved_operations,
+                    "result": result,
+                }
+
+            elif group_name:
+                if not resolved_operations:
+                    raise typer.BadParameter("At least one --operation required when setting group permissions")
+                result = client.set_permissions_to_group_for_space(
+                    space_key,
+                    group_name,
+                    operations=resolved_operations,
+                )
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "group", "name": group_name},
+                    "operations": resolved_operations,
+                    "result": result,
+                }
+
+            elif anonymous:
+                if not resolved_operations:
+                    raise typer.BadParameter("At least one --operation required when setting anonymous permissions")
+                result = client.set_permissions_to_anonymous_for_space(
+                    space_key,
+                    operations=resolved_operations,
+                )
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "anonymous"},
+                    "operations": resolved_operations,
+                    "result": result,
+                }
+
+        elif action == "remove":
+            if not yes:
+                raise typer.BadParameter("--yes required for write operations")
+
+            targets = [bool(user_key), bool(group_name), anonymous]
+            if sum(1 for flag in targets if flag) != 1:
+                raise typer.BadParameter("Provide exactly one of --user, --group, or --anonymous for remove action")
+
+            if user_key:
+                result = client.remove_permissions_from_user_for_space(space_key, user_key)
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "user", "key": user_key},
+                    "result": result,
+                }
+
+            elif group_name:
+                result = client.remove_permissions_from_group_for_space(space_key, group_name)
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "group", "name": group_name},
+                    "result": result,
+                }
+
+            elif anonymous:
+                result = client.remove_permissions_from_anonymous_for_space(space_key)
+                result_payload = {
+                    "space": space_key,
+                    "target": {"type": "anonymous"},
+                    "result": result,
+                }
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("space_permissions_command_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("space_permissions_command_unexpected")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="space-permissions",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("space-management")
+def cmd_space_management(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: archive, trash-list, trash-remove"),
+    space_key: str = typer.Option(..., "--space-key", "-k", help="Confluence space key"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    cursor: str | None = typer.Option(None, "--cursor", help="Pagination cursor for trash-list"),
+    limit: int = typer.Option(50, "--limit", help="Limit for trash-list (max 100)"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions for trash-list"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence space lifecycle operations."""
+
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        if limit < 1 or limit > 100:
+            raise typer.BadParameter("--limit must be between 1 and 100")
+
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        expand_value = expand if expand else None
+        args_summary = [
+            action,
+            f"space={space_key}",
+            f"cursor={cursor}",
+            f"limit={limit}",
+            f"expand={expand_value}",
+        ]
+
+        if action == "archive":
+            if not yes:
+                raise typer.BadParameter("--yes required for archive")
+            result = client.archive_space(space_key)
+            result_payload = {"space": space_key, "action": "archive", "result": result}
+
+        elif action == "trash-list":
+            result = client.get_trashed_contents_by_space(
+                space_key,
+                cursor=cursor,
+                expand=expand_value,
+                limit=limit,
+            )
+            result_payload = {
+                "space": space_key,
+                "action": "trash-list",
+                "result": result,
+            }
+
+        elif action == "trash-remove":
+            if not yes:
+                raise typer.BadParameter("--yes required for trash-remove")
+            result = client.remove_trashed_contents_by_space(space_key)
+            result_payload = {"space": space_key, "action": "trash-remove", "result": result}
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("space_management_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("space_management_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="space-management",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("group")
+def cmd_group(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: list, members"),
+    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name (for members)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    start: int = typer.Option(0, "--start", help="Start index for pagination"),
+    limit: int = typer.Option(1000, "--limit", help="Limit for pagination (max 1000)"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence groups."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        if limit < 1 or limit > 1000:
+            raise typer.BadParameter("--limit must be between 1 and 1000")
+
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action, f"start={start}", f"limit={limit}"]
+
+        if action == "list":
+            result = client.get_all_groups(start=start, limit=limit)
+            result_payload = {"count": len(result), "groups": result}
+
+        elif action == "members":
+            if not group_name:
+                raise typer.BadParameter("--group required for members action")
+            args_summary.append(f"group={group_name}")
+            result = client.get_group_members(group_name, start=start, limit=limit)
+            result_payload = {"group": group_name, "count": len(result), "members": result}
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("group_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("group_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="group",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("user")
+def cmd_user(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: get, password, group-add, group-remove"),
+    username: str | None = typer.Option(None, "--username", "-u", help="Username"),
+    userkey: str | None = typer.Option(None, "--userkey", help="User key"),
+    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name (for group-add/group-remove)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma-separated fields to expand (for get)"),
+    new_password: str | None = typer.Option(None, "--new-password", help="New password (for password)"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence users."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action]
+
+        if action == "get":
+            if not username and not userkey:
+                raise typer.BadParameter("Provide --username or --userkey for get action")
+            if username and userkey:
+                raise typer.BadParameter("Provide either --username or --userkey, not both")
+            expand_value = expand if expand else None
+            args_summary.append(f"username={username}" if username else f"userkey={userkey}")
+            if expand_value:
+                args_summary.append(f"expand={expand_value}")
+
+            if username:
+                result = client.get_user_details_by_username(username, expand=expand_value)
+            else:
+                result = client.get_user_details_by_userkey(userkey, expand=expand_value)
+            result_payload = {"user": result}
+
+        elif action == "password":
+            if not yes:
+                raise typer.BadParameter("--yes required for password change")
+            if not username:
+                raise typer.BadParameter("--username required for password action")
+            if not new_password:
+                raise typer.BadParameter("--new-password required for password action")
+            args_summary.append(f"username={username}")
+            client.change_user_password(username, new_password)
+            result_payload = {"username": username, "status": "password_changed"}
+
+        elif action == "group-add":
+            if not yes:
+                raise typer.BadParameter("--yes required for group-add")
+            if not username:
+                raise typer.BadParameter("--username required for group-add")
+            if not group_name:
+                raise typer.BadParameter("--group required for group-add")
+            args_summary.append(f"username={username}")
+            args_summary.append(f"group={group_name}")
+            client.add_user_to_group(username, group_name)
+            result_payload = {"username": username, "group": group_name, "status": "added"}
+
+        elif action == "group-remove":
+            if not yes:
+                raise typer.BadParameter("--yes required for group-remove")
+            if not username:
+                raise typer.BadParameter("--username required for group-remove")
+            if not group_name:
+                raise typer.BadParameter("--group required for group-remove")
+            args_summary.append(f"username={username}")
+            args_summary.append(f"group={group_name}")
+            client.remove_user_from_group(username, group_name)
+            result_payload = {"username": username, "group": group_name, "status": "removed"}
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("user_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("user_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="user",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("export")
+def cmd_export(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: page, space"),
+    page_id: str | None = typer.Option(None, "--page-id", help="Page ID (for page)"),
+    space_key: str | None = typer.Option(None, "--space-key", "-k", help="Space key (for space)"),
+    export_type: str | None = typer.Option(None, "--export-type", help="Export type: pdf, html, xml (for space)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Output file path (for page PDF)"),
+    api_version: str | None = typer.Option(None, "--api-version", help="API version: cloud, server (for page, auto-detected if not specified)"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Export Confluence pages or spaces."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action]
+
+        if action == "page":
+            if not page_id:
+                raise typer.BadParameter("--page-id required for page action")
+            args_summary.append(f"page_id={page_id}")
+            if api_version:
+                args_summary.append(f"api_version={api_version}")
+
+            pdf_bytes = client.export_page(page_id, api_version=api_version)
+
+            if output:
+                output.write_bytes(pdf_bytes)
+                result_payload = {"page_id": page_id, "output_file": str(output), "size_bytes": len(pdf_bytes)}
+                typer.echo(f"Exported page {page_id} to {output} ({len(pdf_bytes)} bytes)")
+            else:
+                # Write to stdout as binary
+                sys.stdout.buffer.write(pdf_bytes)
+                result_payload = {"page_id": page_id, "size_bytes": len(pdf_bytes), "format": "pdf"}
+
+        elif action == "space":
+            if not space_key:
+                raise typer.BadParameter("--space-key required for space action")
+            if not export_type:
+                raise typer.BadParameter("--export-type required for space action")
+            if export_type not in ("pdf", "html", "xml"):
+                raise typer.BadParameter("--export-type must be one of: pdf, html, xml")
+            args_summary.append(f"space_key={space_key}")
+            args_summary.append(f"export_type={export_type}")
+
+            download_url = client.get_space_export(space_key, export_type)
+            result_payload = {"space_key": space_key, "export_type": export_type, "download_url": download_url}
+
+            if json_output or not sys.stdout.isatty():
+                _emit_json(result_payload)
+            else:
+                typer.echo(f"Space export URL: {download_url}")
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        # For page action, JSON output only if explicitly requested or output file specified
+        if action == "page" and (json_output or output):
+            if json_output:
+                _emit_json(result_payload)
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("export_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("export_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="export",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("draft")
+def cmd_draft(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: get, list, remove"),
+    page_id: str | None = typer.Option(None, "--page-id", help="Page ID (for get/remove)"),
+    space_key: str | None = typer.Option(None, "--space-key", "-k", help="Space key (for list)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    limit: int = typer.Option(25, "--limit", help="Limit for list (max 100)"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operations (for remove)"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence draft pages (Server-only)."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        if limit < 1 or limit > 100:
+            raise typer.BadParameter("--limit must be between 1 and 100")
+
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action]
+
+        if action == "get":
+            if not page_id:
+                raise typer.BadParameter("--page-id required for get action")
+            args_summary.append(f"page_id={page_id}")
+            result = client.get_draft_page_by_id(page_id)
+            result_payload = {"draft_page": result}
+
+        elif action == "list":
+            if not space_key:
+                raise typer.BadParameter("--space-key required for list action")
+            args_summary.append(f"space_key={space_key}")
+            args_summary.append(f"limit={limit}")
+            result = client.get_all_draft_pages_from_space(space_key, limit=limit)
+            result_payload = {"space": space_key, "count": len(result), "drafts": result}
+
+        elif action == "remove":
+            if not yes:
+                raise typer.BadParameter("--yes required for remove action")
+            if not page_id:
+                raise typer.BadParameter("--page-id required for remove action")
+            args_summary.append(f"page_id={page_id}")
+            client.remove_page_as_draft(page_id)
+            result_payload = {"page_id": page_id, "status": "removed"}
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("draft_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("draft_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="draft",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("history")
+def cmd_history(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: get, version, remove"),
+    page_id: str | None = typer.Option(None, "--page-id", help="Page ID"),
+    version: int | None = typer.Option(None, "--version", help="Version number (for version/remove)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operations (for remove)"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence page history and versioning."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action]
+
+        if action == "get":
+            if not page_id:
+                raise typer.BadParameter("--page-id required for get action")
+            args_summary.append(f"page_id={page_id}")
+            result = client.history(page_id)
+            result_payload = {"page_id": page_id, "history": result}
+
+        elif action == "version":
+            if not page_id:
+                raise typer.BadParameter("--page-id required for version action")
+            if version is None:
+                raise typer.BadParameter("--version required for version action")
+            args_summary.append(f"page_id={page_id}")
+            args_summary.append(f"version={version}")
+            result = client.get_content_history_by_version_number(page_id, version)
+            result_payload = {"page_id": page_id, "version": version, "content": result}
+
+        elif action == "remove":
+            if not yes:
+                raise typer.BadParameter("--yes required for remove action (experimental feature)")
+            if not page_id:
+                raise typer.BadParameter("--page-id required for remove action")
+            if version is None:
+                raise typer.BadParameter("--version required for remove action")
+            args_summary.append(f"page_id={page_id}")
+            args_summary.append(f"version={version}")
+            typer.echo("Warning: remove_content_history is an experimental feature", err=True)
+            client.remove_content_history(page_id, version)
+            result_payload = {"page_id": page_id, "version": version, "status": "removed"}
+
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("history_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("history_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="history",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("cache")
+def cmd_cache(
+    ctx: typer.Context,
+    action: str = typer.Argument(..., help="Action: statistics, flush, size"),
+    cache_name: str | None = typer.Option(None, "--cache-name", help="Cache name (for flush)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write operation (for flush)"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Manage Confluence cache (Server-only)."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    args_summary: list[str] = []
+    server_key: str | None = None
+    settings: ConfluenceSettings | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        args_summary = [action]
+
+        if action == "statistics":
+            result = client.get_cache_statistics()
+            result_payload = {"cache_statistics": result}
+        elif action == "flush":
+            if not yes:
+                raise typer.BadParameter("Refusing to flush cache without --yes")
+            if cache_name:
+                args_summary.append(f"cache_name={cache_name}")
+            client.flush_cache(cache_name=cache_name)
+            result_payload = {"status": "success", "cache_flushed": cache_name or "all"}
+        elif action == "size":
+            result = client.get_cache_size()
+            result_payload = {"cache_size": result}
+        else:
+            raise typer.BadParameter(f"Unknown action: {action}")
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("cache_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("cache_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="cache",
+            args=args_summary,
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@app.command("get")
+def cmd_get(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    expand: str | None = typer.Option(
+        None, "--expand", "-e", help="Comma separated expansions (e.g., 'body.storage,version')"
+    ),
+    format: str | None = typer.Option(None, "--format", "-f", help="Output format (storage|editor|view)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    """Get Confluence content by page ID."""
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "get")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+
+    try:
+        client = ContentClientV2(_build_http_client(settings, server_key))
+        content = client.get_content(page_id, expand=_expand_option(expand), format=format)
+
+        if content:
+            _emit_json(content)
+        else:
+            typer.echo(f"Content not found: {page_id}", err=True)
+            raise typer.Exit(code=1) from None
+
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="get",
+            args=[page_id],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+    except Exception as exc:
+        logger.error("get_command_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+# ---------------------------------------------------------------------------
+# Native content commands
+# ---------------------------------------------------------------------------
+
+
+@batch_app.command("scan")
+def batch_scan(
+    ctx: typer.Context,
+    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
+    limit: int = typer.Option(25, "--limit", help="Number of results per request"),
+    max_results: int | None = typer.Option(None, "--max-results", help="Total results to fetch"),
+    start: int = typer.Option(0, "--start", help="Pagination start offset"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "batch.scan")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+    runner = BatchRunner(_build_http_client(settings, server_key), expand=_expand_option(expand))
+    results: list[dict[str, Any]] = []
+    for item in runner.scan(cql, limit=limit, max_results=max_results, start=start):
+        results.append(item)
+    metrics = runner.last_metrics
+    payload: dict[str, Any] = {
+        "cql": cql,
+        "count": len(results),
+        "limit": limit,
+        "maxResults": max_results,
+        "start": start,
+        "results": results,
+    }
+    if metrics is not None:
+        payload["metrics"] = {
+            "requests": metrics.requests,
+            "pagesProcessed": metrics.pages_processed,
+            "durationSeconds": metrics.duration_seconds,
+        }
+    if json_output or not sys.stdout.isatty():
+        _emit_json(payload)
+    else:
+        typer.echo(
+            f"Scanned {payload['count']} results (requests={payload['metrics']['requests'] if 'metrics' in payload else '?'})"
+        )
+    finished_at = datetime.now(UTC)
+    _record_summary(
+        parent_ctx,
+        command="batch.scan",
+        args=[cql, f"limit={limit}", f"start={start}"],
+        server=server_key,
+        exit_code=0,
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+
+
+@batch_app.command("snapshot")
+def batch_snapshot(
+    ctx: typer.Context,
+    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
+    limit: int = typer.Option(25, "--limit", help="Number of results per request"),
+    max_results: int | None = typer.Option(None, "--max-results", help="Total results to fetch"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "batch.snapshot")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+    runner = BatchRunner(_build_http_client(settings, server_key))
+    payload = runner.snapshot(cql, limit=limit, max_results=max_results, expand=_expand_option(expand))
+    _emit_json(payload)
+    finished_at = datetime.now(UTC)
+    _record_summary(
+        parent_ctx,
+        command="batch.snapshot",
+        args=[cql, f"limit={limit}"],
+        server=server_key,
+        exit_code=0,
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+
+
+@batch_app.command("poll")
+def batch_poll(
+    ctx: typer.Context,
+    cql: str = typer.Option(..., "--cql", "-q", help="Base CQL query (will be augmented with lastmodified filter)"),
+    state_file: Path = typer.Option(..., "--state-file", help="Path to persistent cursor file (JSON)"),
+    limit: int = typer.Option(25, "--limit", help="Page size per request"),
+    max_results: int | None = typer.Option(None, "--max-results", help="Max results this run"),
+    expand: str | None = typer.Option(
+        "version", "--expand", help="Comma separated expansions (default includes 'version')"
+    ),
+    out_jsonl: Path | None = typer.Option(None, "--out-jsonl", help="Write results to JSONL (one object per line)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "batch.poll")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+        poller = Poller(client)
+        expand_list = _expand_option(expand) or ["version"]
+        count = poller.poll_once(
+            base_cql=cql,
+            state_file=state_file,
+            limit=limit,
+            max_results=max_results,
+            expand=expand_list,
+            out_jsonl=out_jsonl,
+        )
+        typer.echo(f"Polled {count} items")
+    except Exception as exc:
+        logger.exception("batch.poll failed", extra={"cql": cql})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    finally:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="batch.poll",
+            args=[cql, f"limit={limit}", f"out={str(out_jsonl) if out_jsonl else '-'}"],
+            server=server_key if "server_key" in locals() else "",
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@webhook_app.command("create")
+def webhook_create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", "-n", help="Webhook name"),
+    url: str = typer.Option(..., "--url", help="Destination URL"),
+    event: list[str] = typer.Option(["page_created"], "--event", "-e", help="Event identifier"),
+    active: bool = typer.Option(True, "--active/--inactive", help="Toggle webhook activation"),
+    filters: str | None = typer.Option(None, "--filters", help="JSON object filters"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "webhook.create")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+    client = WebhookClient(_build_http_client(settings, server_key))
+    payload = client.create(
+        name=name,
+        url=url,
+        events=event,
+        active=active,
+        filters=_parse_json_option(filters, "--filters"),
+    )
+    if json_output:
+        _emit_json(payload)
+    else:
+        typer.echo(f"Created webhook {payload.get('id')}")
+    finished_at = datetime.now(UTC)
+    _record_summary(
+        parent_ctx,
+        command="webhook.create",
+        args=[name, f"events={len(event)}"],
+        server=server_key,
+        exit_code=0,
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+
+
+@webhook_app.command("list")
+def webhook_list(
+    ctx: typer.Context,
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "webhook.list")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+    client = WebhookClient(_build_http_client(settings, server_key))
+    payload = client.list()
+    if json_output:
+        _emit_json(payload)
+    else:
+        typer.echo(f"{len(payload)} webhooks")
+    finished_at = datetime.now(UTC)
+    _record_summary(
+        parent_ctx,
+        command="webhook.list",
+        args=[f"count={len(payload)}"],
+        server=server_key,
+        exit_code=0,
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+
+
+@webhook_app.command("delete")
+def webhook_delete(
+    ctx: typer.Context,
+    webhook_id: str = typer.Argument(..., help="Webhook identifier"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "webhook.delete")
+    started_at = datetime.now(UTC)
+    settings = load_settings(strict=True)
+    server_key = _normalise_server(server, settings)
+    client = WebhookClient(_build_http_client(settings, server_key))
+    client.delete(webhook_id)
+    typer.echo(f"Deleted webhook {webhook_id}")
+    finished_at = datetime.now(UTC)
+    _record_summary(
+        parent_ctx,
+        command="webhook.delete",
+        args=[webhook_id],
+        server=server_key,
+        exit_code=0,
+        started_at=started_at,
+        finished_at=finished_at,
+    )
+
+
+@content_app.command("page")
+def content_page(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        cli_ctx = _get_cli_ctx(parent_ctx)
+        client = _build_content_client(settings, server_key, cli_ctx.api_version)
+        expand_list = _expand_option(expand)
+        payload = client.get_page(page_id, expand=expand_list)
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.page failed", extra={"page_id": page_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.page",
+            args=[page_id],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("search")
+def content_search(
+    ctx: typer.Context,
+    cql: str = typer.Argument(..., help="CQL query string"),
+    limit: int = typer.Option(25, "--limit", help="Number of results"),
+    start: int = typer.Option(0, "--start", help="Pagination start"),
+    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    server_key: str = ""
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        cli_ctx = _get_cli_ctx(parent_ctx)
+        client = _build_content_client(settings, server_key, cli_ctx.api_version)
+        expand_list = _expand_option(expand)
+        payload = client.search_cql(cql, limit=limit, start=start, expand=expand_list)
+        _emit_json(payload)
+    except Exception as exc:
+        exit_code = 1
+        logger.exception("content.search failed", extra={"cql": cql})
+        # Provide targeted guidance for CQL auth failures
+        from .errors import ConfluenceAuthError  # local import to avoid top-level cycles
+
+        if isinstance(exc, ConfluenceAuthError):
+            typer.echo("Error: Authentication failed for CQL search.", err=True)
+            typer.echo("Hint: We default to Basic auth (VDS_USERNAME/PASSWORD). If using token, ensure:", err=True)
+            typer.echo("  - Token has permission to use CQL (/rest/api/*search)", err=True)
+            typer.echo("  - Or set VDS_USERNAME/VDS_PASSWORD to use Basic auth", err=True)
+            typer.echo(
+                "  - Quick check: curl -u \"$VDS_USERNAME:$VDS_PASSWORD\" 'http://confluence.digital.vn/rest/api/search?cql=type=page&limit=1'",
+                err=True,
+            )
+        else:
+            typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.search",
+            args=_content_summary_args(cql=cql, limit=limit, start=start),
+            server=server_key,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("templates")
+def content_templates(
+    ctx: typer.Context,
+    space_key: str | None = typer.Option(None, "--space", help="Space key"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        cli_ctx = _get_cli_ctx(parent_ctx)
+        client = _build_content_client(settings, server_key, cli_ctx.api_version)
+        if hasattr(client, "list_templates"):
+            payload = client.list_templates(space_key=space_key)
+        else:
+            payload = {"templates": [], "message": "Templates API not available for this server"}
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.templates failed", extra={"space": space_key})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.templates",
+            args=_content_summary_args(space=space_key or "*"),
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("create-page")
+def content_create_page(
+    ctx: typer.Context,
+    space_key: str = typer.Option(..., "--space", "-S", help="Space key to create the page in"),
+    title: str = typer.Option(..., "--title", "-t", help="Page title"),
+    body_file: Path = typer.Option(
+        ..., "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
+    ),
+    parent_id: str | None = typer.Option(None, "--parent", help="Ancestor page id"),
+    representation: str = typer.Option(
+        "storage", "--representation", help="Content representation (storage, wiki, view)"
+    ),
+    status: str = typer.Option("current", "--status", help="Target page status (current, draft)"),
+    notify_watchers: bool = typer.Option(
+        False, "--notify-watchers/--no-notify-watchers", help="Send notifications to watchers"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.create-page")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        body = _read_text_file(body_file)
+        payload = client.create_page(
+            space_key=space_key,
+            title=title,
+            body=body,
+            parent_id=parent_id,
+            representation=representation,
+            status=status,
+            notify_watchers=notify_watchers,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.create-page failed", extra={"space": space_key, "title": title})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.create-page",
+            args=[f"space={space_key}", f"title={title}"],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("update-page")
+def content_update_page(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    title: str | None = typer.Option(None, "--title", help="New page title"),
+    body_file: Path | None = typer.Option(
+        None, "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
+    ),
+    space_key: str | None = typer.Option(None, "--space", help="Move page to this space"),
+    version: int | None = typer.Option(None, "--version", help="Explicit version number"),
+    representation: str = typer.Option("storage", "--representation", help="Content representation for --body-file"),
+    minor_edit: bool = typer.Option(False, "--minor-edit/--no-minor-edit", help="Mark version as minor edit"),
+    message: str | None = typer.Option(None, "--message", help="Version comment"),
+    status: str = typer.Option("current", "--status", help="Target page status"),
+    notify_watchers: bool = typer.Option(
+        False, "--notify-watchers/--no-notify-watchers", help="Send notifications to watchers"
+    ),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.update-page")
+    if body_file is None and title is None and space_key is None:
+        raise typer.BadParameter("Provide at least one of --title, --body-file or --space")
+    body = _read_text_file(body_file) if body_file else None
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        payload = client.update_page(
+            page_id,
+            title=title,
+            body=body,
+            space_key=space_key,
+            representation=representation,
+            version=version,
+            minor_edit=minor_edit,
+            message=message,
+            status=status,
+            notify_watchers=notify_watchers,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.update-page failed", extra={"page_id": page_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        args = [page_id]
+        if version is not None:
+            args.append(f"version={version}")
+        if title is not None:
+            args.append(f"title={title}")
+        _record_summary(
+            parent_ctx,
+            command="content.update-page",
+            args=args,
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("delete-page")
+def content_delete_page(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    status: str = typer.Option("current", "--status", help="Specify current or draft"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.delete-page")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        client.delete_page(page_id, status=status)
+        typer.echo(f"Deleted page {page_id} (status={status})")
+    except Exception as exc:
+        logger.exception("content.delete-page failed", extra={"page_id": page_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.delete-page",
+            args=[page_id, f"status={status}"],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("add-attachment")
+def content_add_attachment(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    file_path: Path = typer.Option(..., "--file", exists=True, file_okay=True, dir_okay=False, help="File to upload"),
+    filename: str | None = typer.Option(None, "--filename", help="Override uploaded filename"),
+    content_type: str | None = typer.Option(None, "--content-type", help="MIME type for the attachment"),
+    comment: str | None = typer.Option(None, "--comment", help="Attachment comment"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.add-attachment")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        payload = client.upload_attachment(
+            page_id,
+            str(file_path),
+            filename=filename,
+            content_type=content_type,
+            comment=comment,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.add-attachment failed", extra={"page_id": page_id, "file": str(file_path)})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.add-attachment",
+            args=[page_id, file_path.name],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("update-attachment")
+def content_update_attachment(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    attachment_id: str = typer.Argument(..., help="Attachment ID"),
+    file_path: Path = typer.Option(..., "--file", exists=True, file_okay=True, dir_okay=False, help="Replacement file"),
+    filename: str | None = typer.Option(None, "--filename", help="Override uploaded filename"),
+    content_type: str | None = typer.Option(None, "--content-type", help="MIME type for the attachment"),
+    comment: str | None = typer.Option(None, "--comment", help="Attachment comment"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.update-attachment")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        payload = client.update_attachment(
+            page_id,
+            attachment_id,
+            str(file_path),
+            filename=filename,
+            content_type=content_type,
+            comment=comment,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.update-attachment failed", extra={"page_id": page_id, "attachment_id": attachment_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.update-attachment",
+            args=[page_id, attachment_id],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("delete-attachment")
+def content_delete_attachment(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    attachment_id: str | None = typer.Argument(None, help="Attachment ID"),
+    version: int | None = typer.Option(None, "--version", help="Delete a specific attachment version"),
+    filename: str | None = typer.Option(None, "--filename", help="Attachment filename (delete all versions)"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.delete-attachment")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        if not attachment_id and not filename:
+            raise typer.BadParameter("Provide either attachment_id or --filename")
+
+        client = ContentClient(_build_http_client(settings, server_key))
+        client.delete_attachment(page_id, attachment_id=attachment_id, version=version, filename=filename)
+        target = filename or attachment_id
+        typer.echo(f"Deleted attachment {target} from page {page_id}")
+    except Exception as exc:
+        logger.exception("content.delete-attachment failed", extra={"page_id": page_id, "attachment_id": attachment_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.delete-attachment",
+            args=[page_id, filename or attachment_id or "<unspecified>", f"version={version}" if version is not None else "all_versions"],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("ancestors")
+def content_ancestors(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Get page ancestors (parent pages)."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    server_key: str | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        result = client.get_page_ancestors(page_id)
+        result_payload = {"page_id": page_id, "count": len(result), "ancestors": result}
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("content.ancestors_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("content.ancestors_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="content.ancestors",
+            args=[page_id],
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("move")
+def content_move(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    target_title: str = typer.Option(..., "--target-title", help="Target page title to move under"),
+    position: str = typer.Option("append", "--position", help="Position: append, before, after"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm move operation"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Move page to a new location."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    server_key: str | None = None
+
+    try:
+        if not yes:
+            raise typer.BadParameter("--yes required for move operation")
+        if position not in ("append", "before", "after"):
+            raise typer.BadParameter("--position must be one of: append, before, after")
+
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        result = client.move_page(page_id, target_title, position=position)
+        result_payload = {"page_id": page_id, "target_title": target_title, "position": position, "result": result}
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("content.move_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("content.move_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="content.move",
+            args=[page_id, f"target={target_title}", f"position={position}"],
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("tables")
+def content_tables(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Extract tables from page."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    server_key: str | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        result = client.get_tables_from_page(page_id)
+        result_payload = {"page_id": page_id, "count": len(result), "tables": result}
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("content.tables_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("content.tables_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="content.tables",
+            args=[page_id],
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("regex")
+def content_regex(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    pattern: str = typer.Option(..., "--pattern", help="Regex pattern to match"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Extract regex matches from page."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    server_key: str | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        result = client.scrap_regex_from_page(page_id, pattern)
+        result_payload = {"page_id": page_id, "pattern": pattern, "count": len(result), "matches": result}
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("content.regex_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("content.regex_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="content.regex",
+            args=[page_id, f"pattern={pattern}"],
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("restrictions")
+def content_restrictions(
+    ctx: typer.Context,
+    page_id: str = typer.Argument(..., help="Confluence page ID"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
+) -> None:
+    """Get all restrictions for content."""
+    parent_ctx = _parent_context(ctx)
+    started_at = datetime.now(UTC)
+    exit_code = 0
+    result_payload: dict[str, Any] = {}
+    server_key: str | None = None
+
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = _build_http_client(settings, server_key)
+
+        result = client.get_all_restrictions_for_content(page_id)
+        result_payload = {"page_id": page_id, "restrictions": result}
+
+        if json_output or not sys.stdout.isatty():
+            _emit_json(result_payload)
+        else:
+            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
+
+    except (ConfluenceClientError, typer.BadParameter) as exc:
+        exit_code = 1
+        logger.error("content.restrictions_failed: %s", exc)
+        typer.echo(f"Error: {exc}", err=True)
+    except Exception as exc:  # pragma: no cover - unexpected errors
+        exit_code = 1
+        logger.exception("content.restrictions_unexpected_error")
+        typer.echo(f"Error: {exc}", err=True)
+    finally:
+        finished_at = datetime.now(UTC)
+        server_label = server_key or (server.lower() if server else "internal")
+        _record_summary(
+            parent_ctx,
+            command="content.restrictions",
+            args=[page_id],
+            server=server_label,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+        if exit_code != 0:
+            raise typer.Exit(code=exit_code) from None
+
+
+@content_app.command("create-template")
+def content_create_template(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", "-n", help="Template name"),
+    body_file: Path = typer.Option(
+        ..., "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
+    ),
+    template_type: str = typer.Option("page", "--type", help="Template type (page or other supported types)"),
+    space_key: str | None = typer.Option(None, "--space", help="Limit template to space key"),
+    description: str | None = typer.Option(None, "--description", help="Template description"),
+    representation: str = typer.Option("storage", "--representation", help="Content representation"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.create-template")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        body = _read_text_file(body_file)
+        payload = client.create_template(
+            name=name,
+            body=body,
+            template_type=template_type,
+            space_key=space_key,
+            description=description,
+            representation=representation,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.create-template failed", extra={"name": name, "space": space_key})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        args = [name, f"type={template_type}"]
+        if space_key:
+            args.append(f"space={space_key}")
+        _record_summary(
+            parent_ctx,
+            command="content.create-template",
+            args=args,
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("update-template")
+def content_update_template(
+    ctx: typer.Context,
+    template_id: str = typer.Argument(..., help="Template identifier"),
+    name: str | None = typer.Option(None, "--name", help="Template name"),
+    body_file: Path | None = typer.Option(
+        None, "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
+    ),
+    description: str | None = typer.Option(None, "--description", help="Template description"),
+    template_type: str | None = typer.Option(None, "--type", help="Template type"),
+    representation: str = typer.Option("storage", "--representation", help="Representation for --body-file"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.update-template")
+    if name is None and body_file is None and description is None and template_type is None:
+        raise typer.BadParameter("Provide at least one of --name, --body-file, --description, or --type")
+    body = _read_text_file(body_file) if body_file else None
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        payload = client.update_template(
+            template_id,
+            name=name,
+            body=body,
+            description=description,
+            representation=representation,
+            template_type=template_type,
+        )
+        _emit_json(payload)
+    except Exception as exc:
+        logger.exception("content.update-template failed", extra={"template_id": template_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        args = [template_id]
+        if name:
+            args.append(f"name={name}")
+        _record_summary(
+            parent_ctx,
+            command="content.update-template",
+            args=args,
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+@content_app.command("delete-template")
+def content_delete_template(
+    ctx: typer.Context,
+    template_id: str = typer.Argument(..., help="Template identifier"),
+    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
+) -> None:
+    parent_ctx = _parent_context(ctx)
+    _ensure_v1_api(parent_ctx, "content.delete-template")
+    started_at = datetime.now(UTC)
+    try:
+        settings = load_settings(strict=True)
+        server_key = _normalise_server(server, settings)
+        client = ContentClient(_build_http_client(settings, server_key))
+        client.delete_template(template_id)
+        typer.echo(f"Deleted template {template_id}")
+    except Exception as exc:
+        logger.exception("content.delete-template failed", extra={"template_id": template_id})
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+    else:
+        finished_at = datetime.now(UTC)
+        _record_summary(
+            parent_ctx,
+            command="content.delete-template",
+            args=[template_id],
+            server=server_key,
+            exit_code=0,
+            started_at=started_at,
+            finished_at=finished_at,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics
+# ---------------------------------------------------------------------------
+
+
+@app.command("env")
+def cmd_env(ctx: typer.Context) -> None:
+    settings = load_settings(strict=False)
+    typer.echo(
+        f"Default server: {settings.default_server}\n"
+        f"Internal URL: {settings.internal_url}\n"
+        f"External URL: {settings.external_url}\n"
+        f"Internal token set: {bool(settings.internal_token)}\n"
+        f"External token set: {bool(settings.external_token)}"
+    )
+
+
+if __name__ == "__main__":
+    app()