cortexctl 0.1.0.dev20260811135705__py3-none-any.whl

cortex_cli/main.py

@@ -0,0 +1,4878 @@
+from __future__ import annotations
+
+import base64
+import csv
+import json
+import os
+import secrets
+import sys
+import time
+import webbrowser
+import zipfile
+from base64 import urlsafe_b64encode
+from collections.abc import Callable, Sequence
+from dataclasses import asdict
+from datetime import UTC, date, datetime, timedelta
+from hashlib import sha256
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Annotated, Any
+from urllib.parse import parse_qs, urlparse
+from xml.etree import ElementTree
+
+import typer
+from typer._click.exceptions import ClickException, Exit, NoArgsIsHelpError
+
+from cortex_cli.client import CliAPIError, CortexClient
+from cortex_cli.config import CliState, StateStore, default_api_url
+from cortex_cli.registry import COMMAND_GROUPS, CommandSpec
+
+EXIT_SUCCESS = 0
+EXIT_USAGE = 2
+EXIT_AUTH = 10
+EXIT_FORBIDDEN = 11
+EXIT_NOT_FOUND = 12
+EXIT_CONFLICT = 13
+EXIT_ERROR = 20
+
+app = typer.Typer(
+    help="Cortex knowledge base management CLI.",
+    no_args_is_help=True,
+)
+auth_app = typer.Typer(help="Login and inspect identity.", no_args_is_help=True)
+workspace_app = typer.Typer(
+    help="Manage workspaces, invites, and members.",
+    no_args_is_help=True,
+)
+invite_app = typer.Typer(help="Manage workspace invites.", no_args_is_help=True)
+invite_link_app = typer.Typer(
+    help="Manage workspace invite links.",
+    no_args_is_help=True,
+)
+member_app = typer.Typer(help="Manage workspace members.", no_args_is_help=True)
+kb_app = typer.Typer(help="Manage knowledge bases.", no_args_is_help=True)
+kb_order_app = typer.Typer(
+    help="Manage per-user knowledge base ordering.",
+    no_args_is_help=True,
+)
+kb_permissions_app = typer.Typer(
+    help="Manage knowledge base edit permissions.",
+    no_args_is_help=True,
+)
+folder_app = typer.Typer(help="Manage folders.", no_args_is_help=True)
+item_app = typer.Typer(help="Manage knowledge items.", no_args_is_help=True)
+trash_app = typer.Typer(
+    help="Manage deleted knowledge item locations.",
+    no_args_is_help=True,
+)
+file_app = typer.Typer(
+    help="Upload, attach, delete, download, and read files.",
+    no_args_is_help=True,
+)
+pipeline_app = typer.Typer(
+    help="Manage processing pipelines.",
+    no_args_is_help=True,
+)
+processing_app = typer.Typer(
+    help="Trigger and inspect processing.",
+    no_args_is_help=True,
+)
+search_app = typer.Typer(
+    help="Search knowledge items and chunks.",
+    no_args_is_help=True,
+)
+chunk_app = typer.Typer(help="Fetch processed chunks.", no_args_is_help=True)
+source_app = typer.Typer(help="Explore source anchors and pages.", no_args_is_help=True)
+mcp_app = typer.Typer(help="Manage MCP gateway interfaces.", no_args_is_help=True)
+mcp_key_app = typer.Typer(help="Manage MCP API keys.", no_args_is_help=True)
+vector_index_app = typer.Typer(
+    help="Inspect and rebuild workspace vector indexes.",
+    no_args_is_help=True,
+)
+gc_app = typer.Typer(
+    help="Clean physical resources after deletion.",
+    no_args_is_help=True,
+)
+
+app.add_typer(auth_app, name="auth")
+app.add_typer(workspace_app, name="workspace")
+workspace_app.add_typer(invite_app, name="invite")
+workspace_app.add_typer(invite_link_app, name="invite-link")
+workspace_app.add_typer(member_app, name="member")
+app.add_typer(kb_app, name="kb")
+kb_app.add_typer(kb_order_app, name="order")
+kb_app.add_typer(kb_permissions_app, name="permissions")
+app.add_typer(folder_app, name="folder")
+app.add_typer(item_app, name="item")
+app.add_typer(trash_app, name="trash")
+app.add_typer(file_app, name="file")
+app.add_typer(pipeline_app, name="pipeline")
+app.add_typer(processing_app, name="processing")
+app.add_typer(search_app, name="search")
+app.add_typer(chunk_app, name="chunk")
+app.add_typer(source_app, name="source")
+app.add_typer(mcp_app, name="mcp")
+mcp_app.add_typer(mcp_key_app, name="key")
+app.add_typer(vector_index_app, name="vector-index")
+app.add_typer(gc_app, name="gc")
+
+GLOBAL_JSON = False
+GLOBAL_API_URL: str | None = None
+GLOBAL_PROFILE = "full"
+
+PROFILE_FULL = "full"
+PROFILE_AGENT_READONLY = "agent-readonly"
+ROOT_OPTIONS_WITH_VALUE = {"--api-url", "--profile"}
+ROOT_FLAGS = {"--json"}
+TOP_LEVEL_COMMANDS = {"version", "doctor", "commands", "help", "recall"}
+NESTED_GROUPS = {
+    ("workspace", "invite"),
+    ("workspace", "invite-link"),
+    ("workspace", "member"),
+    ("kb", "order"),
+    ("kb", "permissions"),
+    ("mcp", "key"),
+}
+READONLY_ALLOWED_COMMANDS = {
+    ("version",),
+    ("doctor",),
+    ("commands",),
+    ("help",),
+    ("auth", "login"),
+    ("auth", "whoami"),
+    ("auth", "logout"),
+    ("workspace", "list"),
+    ("workspace", "use"),
+    ("workspace", "get"),
+    ("workspace", "invite-link", "enter"),
+    ("kb", "list"),
+    ("kb", "get"),
+    ("folder", "tree"),
+    ("item", "list"),
+    ("item", "get"),
+    ("file", "list"),
+    ("file", "preview"),
+    ("file", "read"),
+    ("search", "grep"),
+    ("search", "advanced"),
+    ("search", "semantic"),
+    ("recall",),
+    ("chunk", "get"),
+    ("chunk", "context"),
+    ("source", "locate"),
+    ("source", "expand"),
+    ("source", "page"),
+    ("source", "region-image"),
+    ("processing", "status"),
+    ("processing", "get"),
+    ("vector-index", "status"),
+}
+MCP_TOOL_NAMES = {
+    "grep",
+    "recall",
+    "get_chunk",
+    "source_locate",
+    "source_expand",
+    "read_page",
+    "read_region_image",
+    "list_kb",
+    "get_item",
+    "get_file",
+}
+KNOWN_COMMAND_PATHS = {
+    (group.name, *leaf.name.split())
+    for group in COMMAND_GROUPS
+    for leaf in group.commands
+}
+KNOWN_COMMAND_PATHS.update((command,) for command in TOP_LEVEL_COMMANDS)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    global GLOBAL_PROFILE
+    args = list(argv) if argv is not None else sys.argv[1:]
+    profile_or_error = resolve_cli_profile(args)
+    if isinstance(profile_or_error, CliAPIError):
+        emit_cli_error(json_requested(args), profile_or_error)
+        return EXIT_USAGE
+    GLOBAL_PROFILE = profile_or_error
+    guard_error = profile_guard_error(args, profile_or_error)
+    if guard_error is not None:
+        emit_cli_error(json_requested(args), guard_error)
+        return EXIT_FORBIDDEN
+
+    command = typer.main.get_command(app)
+    try:
+        result = command.main(
+            args=args,
+            prog_name="cortex",
+            standalone_mode=False,
+        )
+    except Exit as exc:
+        return int(exc.exit_code)
+    except NoArgsIsHelpError:
+        return EXIT_SUCCESS
+    except ClickException as exc:
+        exc.show(file=sys.stderr)
+        return EXIT_USAGE
+
+    return result if isinstance(result, int) else EXIT_SUCCESS
+
+
+def resolve_cli_profile(args: Sequence[str]) -> str | CliAPIError:
+    explicit = profile_from_args(args)
+    raw = (
+        explicit
+        or os.environ.get("CORTEX_CLI_PROFILE")
+        or os.environ.get("CORTEX_CLI_MODE")
+        or PROFILE_FULL
+    )
+    profile = normalize_cli_profile(raw)
+    if profile is None:
+        return CliAPIError(
+            code="cli.invalid_profile",
+            message=(
+                "CLI profile must be full or agent-readonly "
+                "(readonly is accepted as an alias)."
+            ),
+            status_code=400,
+            details={"profile": raw},
+        )
+    return profile
+
+
+def normalize_cli_profile(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().casefold().replace("_", "-")
+    if normalized in {"", "full", "default"}:
+        return PROFILE_FULL
+    if normalized in {"readonly", "read-only", "agent-readonly"}:
+        return PROFILE_AGENT_READONLY
+    return None
+
+
+def profile_from_args(args: Sequence[str]) -> str | None:
+    for index, arg in enumerate(args):
+        if arg == "--profile" and index + 1 < len(args):
+            return args[index + 1]
+        if arg.startswith("--profile="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+def json_requested(args: Sequence[str]) -> bool:
+    return "--json" in args
+
+
+def profile_guard_error(args: Sequence[str], profile: str) -> CliAPIError | None:
+    if profile != PROFILE_AGENT_READONLY:
+        return None
+    if any(arg in {"--help", "-h"} for arg in args):
+        return None
+    command_path = command_path_from_args(args)
+    if not command_path:
+        return None
+    if command_path in READONLY_ALLOWED_COMMANDS:
+        # Retrieval-only: allow image bytes in JSON, forbid local filesystem writes.
+        if command_path in {("source", "page"), ("source", "region-image")} and (
+            args_request_output_file(args)
+        ):
+            return CliAPIError(
+                code="cli.profile_forbidden",
+                message=(
+                    "CLI profile agent-readonly forbids --output/-o "
+                    "(local file write). Use --include-bytes for vision pixels."
+                ),
+                status_code=403,
+                details={
+                    "profile": profile,
+                    "command": "cortex " + " ".join(command_path),
+                    "flag": "--output",
+                },
+            )
+        return None
+    if command_is_incomplete_group(command_path):
+        return None
+    if command_path not in KNOWN_COMMAND_PATHS:
+        return None
+    command = "cortex " + " ".join(command_path)
+    return CliAPIError(
+        code="cli.profile_forbidden",
+        message=(
+            "CLI profile agent-readonly only allows discovery, auth, workspace "
+            "selection, and read-only knowledge retrieval commands."
+        ),
+        status_code=403,
+        details={
+            "profile": profile,
+            "command": command,
+            "allowed": sorted(" ".join(path) for path in READONLY_ALLOWED_COMMANDS),
+        },
+    )
+
+
+def args_request_output_file(args: Sequence[str]) -> bool:
+    """True when argv requests CLI --output/-o (local path write)."""
+    return any(arg in {"-o", "--output"} or arg.startswith("--output=") for arg in args)
+
+
+def command_is_incomplete_group(command_path: tuple[str, ...]) -> bool:
+    return any(
+        known[: len(command_path)] == command_path and len(command_path) < len(known)
+        for known in KNOWN_COMMAND_PATHS
+    )
+
+
+def command_path_from_args(args: Sequence[str]) -> tuple[str, ...]:
+    tokens = command_tokens(args)
+    if not tokens:
+        return ()
+    first = tokens[0]
+    if first in TOP_LEVEL_COMMANDS:
+        return (first,)
+    if len(tokens) == 1 or tokens[1].startswith("-"):
+        return (first,)
+    if len(tokens) >= 2 and (first, tokens[1]) in NESTED_GROUPS:
+        if len(tokens) == 2 or tokens[2].startswith("-"):
+            return (first, tokens[1])
+        return (first, tokens[1], tokens[2])
+    return (first, tokens[1])
+
+
+def command_tokens(args: Sequence[str]) -> list[str]:
+    tokens = list(args)
+    index = 0
+    while index < len(tokens):
+        arg = tokens[index]
+        if (
+            arg in ROOT_FLAGS
+            or arg.startswith("--api-url=")
+            or arg.startswith("--profile=")
+        ):
+            index += 1
+            continue
+        if arg in ROOT_OPTIONS_WITH_VALUE:
+            index += 2
+            continue
+        if arg.startswith("-"):
+            index += 1
+            continue
+        return tokens[index:]
+    return []
+
+
+@app.callback()
+def app_callback(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON where supported.",
+    ),
+    api_url: str | None = typer.Option(
+        None,
+        "--api-url",
+        help="Backend API base URL. Defaults to CORTEX_API_URL or local backend.",
+    ),
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        help="Execution profile: full or agent-readonly.",
+    ),
+) -> None:
+    global GLOBAL_API_URL, GLOBAL_JSON, GLOBAL_PROFILE
+    GLOBAL_JSON = json_output
+    GLOBAL_API_URL = api_url.rstrip("/") if api_url else None
+    if profile is not None:
+        GLOBAL_PROFILE = normalize_cli_profile(profile) or PROFILE_FULL
+
+
+@app.command()
+def version(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output version as JSON.",
+    ),
+) -> int:
+    _emit({"cli": "cortex", "version": "0.1.0"}, json_for(json_output))
+    return EXIT_SUCCESS
+
+
+@app.command()
+def doctor(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output checks as JSON.",
+    ),
+) -> int:
+    store = StateStore()
+    state = load_state(store)
+    client = client_from_state(store, state)
+    checks = [
+        {
+            "name": "cli_package",
+            "status": "ok",
+            "message": "Python CLI package is importable.",
+        },
+        {
+            "name": "api_url",
+            "status": "ok" if state.api_url else "error",
+            "message": state.api_url or "API URL is not configured.",
+        },
+        doctor_api_check("health", lambda: client.health()),
+        doctor_api_check("ready", lambda: client.ready()),
+        {
+            "name": "state_file",
+            "status": "ok" if store.path.exists() else "warn",
+            "message": str(store.path),
+        },
+        doctor_token_check(state, client),
+        doctor_workspace_check(state, client),
+    ]
+    status = "error" if any(item["status"] == "error" for item in checks) else "ok"
+    payload = {"status": status, "checks": checks}
+    _emit(payload, json_for(json_output))
+    return EXIT_SUCCESS if status == "ok" else EXIT_ERROR
+
+
+@app.command("commands")
+def list_commands(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output the command tree as JSON.",
+    ),
+) -> int:
+    payload = {"groups": [group_to_dict(group) for group in COMMAND_GROUPS]}
+
+    if json_for(json_output):
+        _emit(payload, json_output=True)
+        return EXIT_SUCCESS
+
+    for group in COMMAND_GROUPS:
+        print(f"{group.name}: {group.description}")
+        for command in group.commands:
+            print(f"  cortex {group.name} {command.name} - {command.description}")
+
+    return EXIT_SUCCESS
+
+
+@app.command("help")
+def structured_help(
+    topic: Annotated[
+        list[str] | None,
+        typer.Argument(help="Command group or command path."),
+    ] = None,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output help as JSON.",
+    ),
+) -> int:
+    selected_topic = topic[0] if topic else None
+    group = next((item for item in COMMAND_GROUPS if item.name == selected_topic), None)
+
+    if selected_topic and group is None:
+        payload = {
+            "error": {
+                "code": "cli.topic_not_found",
+                "message": f"Unknown help topic: {selected_topic}",
+                "details": {"topic": selected_topic},
+            }
+        }
+        _emit(payload, json_output=True)
+        return EXIT_USAGE
+
+    groups = [group] if group else COMMAND_GROUPS
+    payload = {"groups": [group_to_dict(item) for item in groups]}
+
+    if json_for(json_output):
+        _emit(payload, json_output=True)
+        return EXIT_SUCCESS
+
+    for item in groups:
+        print(f"{item.name}: {item.description}")
+        print(f"  permission: {item.permission}")
+        for command in item.commands:
+            print(f"  cortex {item.name} {command.name}")
+            print(f"    {command.description}")
+
+    return EXIT_SUCCESS
+
+
+@auth_app.command("login")
+def auth_login(
+    email: str | None = typer.Option(None, "--email", help="Debug login email."),
+    method: str = typer.Option(
+        "device",
+        "--method",
+        help="Login method: device or loopback. Ignored when --email is provided.",
+    ),
+    password: str | None = typer.Option(
+        None,
+        "--password",
+        help="Debug login password.",
+    ),
+    display_name: str | None = typer.Option(
+        None,
+        "--display-name",
+        help="Display name for first debug login.",
+    ),
+    no_browser: bool = typer.Option(
+        False,
+        "--no-browser",
+        help="Print the authorization URL instead of opening a browser.",
+    ),
+    timeout_seconds: int = typer.Option(
+        180,
+        "--timeout-seconds",
+        min=1,
+        help="Seconds to wait for browser authorization.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    store = StateStore()
+    state = load_state(store)
+    client = CortexClient(base_url=state.api_url)
+    return run_cli_action(
+        json_for(json_output),
+        lambda: auth_login_action(
+            email=email,
+            method=method,
+            password=password,
+            display_name=display_name,
+            no_browser=no_browser,
+            timeout_seconds=timeout_seconds,
+            json_output=json_for(json_output),
+            store=store,
+            state=state,
+            client=client,
+        ),
+    )
+
+
+@auth_app.command("whoami")
+def auth_whoami(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(json_for(json_output), lambda: client_for().me())
+
+
+@auth_app.command("logout")
+def auth_logout(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    def action() -> dict[str, str]:
+        store = StateStore()
+        state = load_state(store)
+        client = client_from_state(store, state)
+        try:
+            if state.refresh_token:
+                client.revoke(state.refresh_token)
+        finally:
+            store.clear_token()
+        return {"status": "ok"}
+
+    return run_cli_action(json_for(json_output), action)
+
+
+@workspace_app.command("list")
+def workspace_list(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().workspace_panel(),
+        text_renderer=render_workspace_panel,
+    )
+
+
+@workspace_app.command("create")
+def workspace_create(
+    name: str = typer.Option(..., "--name", help="Workspace name."),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Workspace description.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_workspace(
+            name=name,
+            description=description,
+        ),
+    )
+
+
+@workspace_app.command("use")
+def workspace_use(
+    workspace_id: str,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    def action() -> dict[str, Any]:
+        store = StateStore()
+        state = load_state(store)
+        client = client_from_state(store, state)
+        workspace = client.get_workspace(workspace_id)
+        state.default_workspace_id = workspace_id
+        store.save(state)
+        return {
+            "status": "ok",
+            "default_workspace_id": workspace_id,
+            "workspace": workspace,
+        }
+
+    return run_cli_action(json_for(json_output), action)
+
+
+@workspace_app.command("get")
+def workspace_get(
+    workspace_id: str | None = typer.Argument(None),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().get_workspace(resolve_workspace_id(workspace_id)),
+    )
+
+
+@workspace_app.command("update")
+def workspace_update(
+    workspace_id: str | None = typer.Argument(None),
+    name: str | None = typer.Option(None, "--name", help="Workspace name."),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Workspace description.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if name is None and description is None:
+        return emit_usage_error(
+            json_for(json_output),
+            "workspace.update_requires_change",
+            "Provide --name or --description.",
+        )
+
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().update_workspace(
+            resolve_workspace_id(workspace_id),
+            name=name,
+            description=description,
+        ),
+    )
+
+
+@workspace_app.command("delete")
+def workspace_delete(
+    workspace_id: str | None = typer.Argument(None),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: no_content_payload(
+            "workspace.deleted",
+            client_for().delete_workspace(resolve_workspace_id(workspace_id)),
+        ),
+    )
+
+
+@workspace_app.command("leave")
+def workspace_leave(
+    workspace_id: str | None = typer.Argument(None),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: no_content_payload(
+            "workspace.left",
+            client_for().leave_workspace(resolve_workspace_id(workspace_id)),
+        ),
+    )
+
+
+@workspace_app.command("transfer-owner")
+def workspace_transfer_owner(
+    workspace_id: str | None = typer.Argument(None),
+    new_owner_id: str = typer.Option(..., "--new-owner-id", help="New owner user id."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().transfer_owner(
+            resolve_workspace_id(workspace_id),
+            new_owner_id=new_owner_id,
+        ),
+    )
+
+
+@invite_app.command("list")
+def invite_list(
+    workspace_id: str | None = typer.Argument(None),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    query: str | None = typer.Option(None, "--query", help="Search invite email."),
+    status: str = typer.Option(
+        "pending",
+        "--status",
+        help="Invite status: pending, accepted, revoked or rejected.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if status not in {"pending", "accepted", "revoked", "rejected"}:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "--status must be pending, accepted, revoked or rejected.",
+        )
+
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().list_invites(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+            query=query,
+            status=status,
+        ),
+        text_renderer=render_invite_list,
+    )
+
+
+@invite_app.command("create")
+def invite_create(
+    workspace_id: str | None = typer.Argument(None),
+    email: str = typer.Option(..., "--email", help="Invitee email."),
+    role: str = typer.Option(..., "--role", help="Invite role: editor or viewer."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if role not in {"editor", "viewer"}:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "--role must be editor or viewer.",
+        )
+
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_invite(
+            resolve_workspace_id(workspace_id),
+            email=email,
+            role=role,
+        ),
+    )
+
+
+@invite_app.command("revoke")
+def invite_revoke(
+    invite_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: no_content_payload(
+            "invite.revoked",
+            client_for().revoke_invite(resolve_workspace_id(workspace_id), invite_id),
+        ),
+    )
+
+
+@invite_app.command("enter")
+def invite_enter(
+    invite_id: str,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().enter_invite(invite_id),
+    )
+
+
+@invite_app.command("reject")
+def invite_reject(
+    invite_id: str,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().reject_invite(invite_id),
+    )
+
+
+@invite_link_app.command("list")
+def invite_link_list(
+    workspace_id: str | None = typer.Argument(None),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().list_invite_links(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+        ),
+        text_renderer=render_invite_link_list,
+    )
+
+
+@invite_link_app.command("create")
+def invite_link_create(
+    workspace_id: str | None = typer.Argument(None),
+    name: str = typer.Option("公共入口链接", "--name", help="Invite link name."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_invite_link(
+            resolve_workspace_id(workspace_id),
+            name=name,
+        ),
+        text_renderer=render_invite_link_created,
+    )
+
+
+@invite_link_app.command("revoke")
+def invite_link_revoke(
+    link_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: no_content_payload(
+            "invite_link.revoked",
+            client_for().revoke_invite_link(
+                resolve_workspace_id(workspace_id),
+                link_id,
+            ),
+        ),
+    )
+
+
+@invite_link_app.command("enter")
+def invite_link_enter(
+    token_or_url: str,
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().enter_invite_link(token_or_url),
+    )
+
+
+@member_app.command("list")
+def member_list(
+    workspace_id: str | None = typer.Argument(None),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    query: str | None = typer.Option(None, "--query", help="Search name or email."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().list_members(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+            query=query,
+        ),
+        text_renderer=render_member_list,
+    )
+
+
+@member_app.command("set-role")
+def member_set_role(
+    user_id: str,
+    role: str = typer.Option(..., "--role", help="Member role: editor or viewer."),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if role not in {"editor", "viewer"}:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "--role must be editor or viewer.",
+        )
+
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().update_member_role(
+            resolve_workspace_id(workspace_id),
+            user_id,
+            role=role,
+        ),
+    )
+
+
+@member_app.command("remove")
+def member_remove(
+    user_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: no_content_payload(
+            "member.removed",
+            client_for().remove_member(resolve_workspace_id(workspace_id), user_id),
+        ),
+    )
+
+
+@kb_app.command("list")
+def kb_list(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    query: str | None = typer.Option(
+        None,
+        "--query",
+        help="Search name or description.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().list_knowledge_bases(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+            query=query,
+        ),
+        text_renderer=render_kb_list,
+    )
+
+
+@kb_app.command("create")
+def kb_create(
+    name: str = typer.Option(..., "--name", help="Knowledge base name."),
+    description: str | None = typer.Option(None, "--description"),
+    pipeline_id: str | None = typer.Option(None, "--pipeline-id"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_knowledge_base(
+            resolve_workspace_id(workspace_id),
+            name=name,
+            description=description,
+            pipeline_id=pipeline_id,
+        ),
+    )
+
+
+@kb_app.command("get")
+def kb_get(
+    kb_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().get_knowledge_base(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+        ),
+    )
+
+
+@kb_app.command("update")
+def kb_update(
+    kb_id: str,
+    name: str | None = typer.Option(None, "--name"),
+    description: str | None = typer.Option(None, "--description"),
+    pipeline_id: str | None = typer.Option(None, "--pipeline-id"),
+    clear_pipeline: bool = typer.Option(False, "--clear-pipeline"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if pipeline_id and clear_pipeline:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "Use either --pipeline-id or --clear-pipeline.",
+        )
+    payload = compact_payload(
+        {
+            "name": name,
+            "description": description,
+            "pipeline_id": None if clear_pipeline else pipeline_id,
+        },
+        force_keys={"pipeline_id"} if clear_pipeline else set(),
+    )
+    if not payload:
+        return emit_usage_error(
+            json_for(json_output),
+            "kb.update_requires_change",
+            "Provide --name, --description, --pipeline-id or --clear-pipeline.",
+        )
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().update_knowledge_base(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+            payload,
+        ),
+    )
+
+
+@kb_app.command("delete")
+def kb_delete(
+    kb_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return destructive_action(
+        json_for(json_output),
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={"status": "dry_run", "action": "kb.delete", "kb_id": kb_id},
+        action=lambda: no_content_payload(
+            "kb.deleted",
+            client_for().delete_knowledge_base(
+                resolve_workspace_id(workspace_id),
+                kb_id,
+            ),
+        ),
+    )
+
+
+@kb_order_app.command("set")
+def kb_order_set(
+    kb_order: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--kb-order",
+            help="Knowledge base order entry as <kb-id>:<sort-order>.",
+        ),
+    ] = None,
+    clear: bool = typer.Option(
+        False,
+        "--clear",
+        help="Clear the current user's custom knowledge base order.",
+    ),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    parsed_order = parse_kb_order_options(kb_order, json_enabled)
+    if isinstance(parsed_order, int):
+        return parsed_order
+    if clear and parsed_order:
+        return emit_usage_error(
+            json_enabled,
+            "kb.order_clear_conflict",
+            "Use either --clear or --kb-order entries, not both.",
+        )
+    if not clear and not parsed_order:
+        return emit_usage_error(
+            json_enabled,
+            "kb.order_requires_items",
+            "Provide at least one --kb-order <kb-id>:<sort-order> entry or --clear.",
+        )
+    order_items = [] if clear else parsed_order
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().update_knowledge_base_order(
+            resolve_workspace_id(workspace_id),
+            order_items,
+        ),
+        text_renderer=render_kb_order,
+    )
+
+
+@kb_permissions_app.command("get")
+def kb_permissions_get(
+    kb_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().get_knowledge_base_permissions(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+        ),
+        text_renderer=render_kb_permissions,
+    )
+
+
+@kb_permissions_app.command("set")
+def kb_permissions_set(
+    kb_id: str,
+    edit_policy: str = typer.Option(
+        ...,
+        "--edit-policy",
+        help="all_editors or selected_editors.",
+    ),
+    editor_user_id: Annotated[
+        list[str] | None,
+        typer.Option("--editor-user-id"),
+    ] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if edit_policy not in {
+        "all_editors",
+        "selected_editors",
+    }:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "--edit-policy must be all_editors or selected_editors.",
+        )
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().update_knowledge_base_permissions(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+            edit_policy=edit_policy,
+            editor_user_ids=editor_user_id or [],
+        ),
+        text_renderer=render_kb_permissions,
+    )
+
+
+@folder_app.command("tree")
+def folder_tree(
+    kb_id: str = typer.Option(..., "--kb", help="Knowledge base id."),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().get_folder_tree(resolve_workspace_id(workspace_id), kb_id),
+        text_renderer=render_folder_tree,
+    )
+
+
+@folder_app.command("mkdir")
+def folder_mkdir(
+    kb_id: str = typer.Option(..., "--kb", help="Knowledge base id."),
+    name: str = typer.Option(..., "--name", help="Folder name."),
+    parent_id: str | None = typer.Option(None, "--parent-id"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_folder(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+            name=name,
+            parent_id=parent_id,
+        ),
+    )
+
+
+@folder_app.command("mv")
+def folder_mv(
+    folder_id: str,
+    kb_id: str = typer.Option(..., "--kb", help="Knowledge base id."),
+    name: str | None = typer.Option(None, "--name"),
+    parent_id: str | None = typer.Option(None, "--parent-id"),
+    root: bool = typer.Option(False, "--root", help="Move folder to KB root."),
+    sort_order: int | None = typer.Option(None, "--sort-order"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    if parent_id and root:
+        return emit_usage_error(
+            json_for(json_output),
+            "validation.invalid",
+            "Use either --parent-id or --root.",
+        )
+    payload = compact_payload(
+        {"name": name, "parent_id": parent_id, "sort_order": sort_order},
+        force_keys={"parent_id"} if root else set(),
+    )
+    if not payload:
+        return emit_usage_error(
+            json_for(json_output),
+            "folder.mv_requires_change",
+            "Provide --name, --parent-id, --root or --sort-order.",
+        )
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().update_folder(
+            resolve_workspace_id(workspace_id),
+            kb_id,
+            folder_id,
+            payload,
+        ),
+    )
+
+
+@folder_app.command("rm")
+def folder_rm(
+    folder_id: str,
+    kb_id: str = typer.Option(..., "--kb", help="Knowledge base id."),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return destructive_action(
+        json_for(json_output),
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "folder.rm",
+            "folder_id": folder_id,
+            "kb_id": kb_id,
+        },
+        action=lambda: no_content_payload(
+            "folder.deleted",
+            client_for().delete_folder(
+                resolve_workspace_id(workspace_id),
+                kb_id,
+                folder_id,
+            ),
+        ),
+    )
+
+
+@item_app.command("list")
+def item_list(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    query: str | None = typer.Option(None, "--query", help="Search title."),
+    available: bool = typer.Option(
+        False,
+        "--available",
+        help="Filter available items.",
+    ),
+    unavailable: bool = typer.Option(
+        False,
+        "--unavailable",
+        help="Filter unavailable items.",
+    ),
+    locked: bool = typer.Option(False, "--locked", help="Filter locked items."),
+    unlocked: bool = typer.Option(False, "--unlocked", help="Filter unlocked items."),
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    unclassified: bool = typer.Option(False, "--unclassified"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    is_available = resolve_bool_filter(
+        positive=available,
+        negative=unavailable,
+        positive_name="--available",
+        negative_name="--unavailable",
+        json_output=json_enabled,
+    )
+    if type(is_available) is int:
+        return is_available
+    is_locked = resolve_bool_filter(
+        positive=locked,
+        negative=unlocked,
+        positive_name="--locked",
+        negative_name="--unlocked",
+        json_output=json_enabled,
+    )
+    if type(is_locked) is int:
+        return is_locked
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_items(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+            query=query,
+            is_available=is_available,
+            is_locked=is_locked,
+            kb_id=kb_id,
+            folder_id=folder_id,
+            unclassified=unclassified,
+        ),
+        text_renderer=render_item_list,
+    )
+
+
+@item_app.command("get")
+def item_get(
+    item_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().get_item(resolve_workspace_id(workspace_id), item_id),
+    )
+
+
+@item_app.command("create")
+def item_create(
+    title: str = typer.Option(..., "--title"),
+    unavailable: bool = typer.Option(
+        False,
+        "--unavailable",
+        help="Create item outside default search and recall.",
+    ),
+    locked: bool = typer.Option(
+        False,
+        "--locked",
+        "--lock",
+        help="Create locked item.",
+    ),
+    pipeline_id: str | None = typer.Option(None, "--pipeline-id"),
+    processing_config: str | None = typer.Option(None, "--processing-config-json"),
+    metadata: Annotated[list[str] | None, typer.Option("--metadata")] = None,
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    payload_or_error = build_item_payload(
+        title=title,
+        is_available=not unavailable,
+        is_locked=locked,
+        pipeline_id=pipeline_id,
+        processing_config=processing_config,
+        metadata=metadata,
+        kb_id=kb_id,
+        folder_id=folder_id,
+        json_output=json_enabled,
+    )
+    if isinstance(payload_or_error, int):
+        return payload_or_error
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().create_item(
+            resolve_workspace_id(workspace_id),
+            payload_or_error,
+        ),
+    )
+
+
+@item_app.command("update")
+def item_update(
+    item_id: str,
+    title: str | None = typer.Option(None, "--title"),
+    available: bool = typer.Option(
+        False,
+        "--available",
+        help="Mark item available.",
+    ),
+    unavailable: bool = typer.Option(
+        False,
+        "--unavailable",
+        help="Mark item unavailable.",
+    ),
+    lock_item: bool = typer.Option(False, "--lock", help="Lock item writes."),
+    unlock_item: bool = typer.Option(False, "--unlock", help="Unlock item writes."),
+    pipeline_id: str | None = typer.Option(None, "--pipeline-id"),
+    clear_pipeline: bool = typer.Option(False, "--clear-pipeline"),
+    processing_config: str | None = typer.Option(None, "--processing-config-json"),
+    metadata: Annotated[list[str] | None, typer.Option("--metadata")] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    if pipeline_id and clear_pipeline:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "Use either --pipeline-id or --clear-pipeline.",
+        )
+    is_available = resolve_bool_filter(
+        positive=available,
+        negative=unavailable,
+        positive_name="--available",
+        negative_name="--unavailable",
+        json_output=json_enabled,
+    )
+    if type(is_available) is int:
+        return is_available
+    is_locked = resolve_bool_filter(
+        positive=lock_item,
+        negative=unlock_item,
+        positive_name="--lock",
+        negative_name="--unlock",
+        json_output=json_enabled,
+    )
+    if type(is_locked) is int:
+        return is_locked
+    parsed_config = parse_json_object(processing_config, json_enabled)
+    if isinstance(parsed_config, int):
+        return parsed_config
+    parsed_metadata = parse_metadata_options(metadata, json_enabled)
+    if isinstance(parsed_metadata, int):
+        return parsed_metadata
+    payload = compact_payload(
+        {
+            "title": title,
+            "is_available": is_available,
+            "is_locked": is_locked,
+            "pipeline_id": None if clear_pipeline else pipeline_id,
+            "processing_config": parsed_config,
+        },
+        force_keys={"pipeline_id"} if clear_pipeline else set(),
+    )
+    if not payload and metadata is None:
+        return emit_usage_error(
+            json_enabled,
+            "item.update_requires_change",
+            "Provide an item field or --metadata.",
+        )
+
+    def action() -> dict[str, Any]:
+        workspace = resolve_workspace_id(workspace_id)
+        client = client_for()
+        item = (
+            client.update_item(workspace, item_id, payload)
+            if payload
+            else client.get_item(workspace, item_id)
+        )
+        if metadata is not None:
+            item = client.replace_item_metadata(workspace, item_id, parsed_metadata)
+        return item
+
+    return run_cli_action(json_enabled, action)
+
+
+@item_app.command("delete")
+def item_delete(
+    item_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return destructive_action(
+        json_for(json_output),
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "item.delete",
+            "item_id": item_id,
+        },
+        action=lambda: no_content_payload(
+            "item.deleted",
+            client_for().delete_item(resolve_workspace_id(workspace_id), item_id),
+        ),
+    )
+
+
+@item_app.command("mount")
+def item_mount(
+    item_id: str,
+    kb_id: str = typer.Option(..., "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().create_item_mount(
+            resolve_workspace_id(workspace_id),
+            item_id,
+            kb_id=kb_id,
+            folder_id=folder_id,
+        ),
+    )
+
+
+@item_app.command("unmount")
+def item_unmount(
+    item_id: str,
+    kb_id: str = typer.Option(..., "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().delete_item_mount(
+            resolve_workspace_id(workspace_id),
+            item_id,
+            kb_id=kb_id,
+            folder_id=folder_id,
+        ),
+    )
+
+
+@trash_app.command("list")
+def trash_list(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return run_cli_action(
+        json_for(json_output),
+        lambda: client_for().list_trash_entries(
+            resolve_workspace_id(workspace_id),
+            page=page,
+            page_size=page_size,
+        ),
+        text_renderer=render_trash_list,
+    )
+
+
+@trash_app.command("restore")
+def trash_restore(
+    entry_id: str,
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    item_id: str | None = typer.Option(None, "--item"),
+    unclassified: bool = typer.Option(False, "--unclassified"),
+    original: bool = typer.Option(False, "--original"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    selected_targets = [
+        bool(kb_id),
+        bool(folder_id),
+        bool(item_id),
+        unclassified,
+        original,
+    ]
+    if sum(selected_targets) != 1:
+        return emit_usage_error(
+            json_enabled,
+            "trash.restore_target_required",
+            "Provide exactly one of --kb, --folder, --item, "
+            "--unclassified, or --original.",
+        )
+
+    def action() -> dict[str, Any]:
+        workspace = resolve_workspace_id(workspace_id)
+        client = client_for()
+        target = trash_restore_target(
+            kb_id=kb_id,
+            folder_id=folder_id,
+            item_id=item_id,
+            unclassified=unclassified,
+            original=original,
+        )
+        return client.restore_trash_entry(
+            workspace,
+            entry_id,
+            target=target,
+        )
+
+    return run_cli_action(
+        json_enabled,
+        action,
+    )
+
+
+@trash_app.command("purge")
+def trash_purge(
+    entry_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return destructive_action(
+        json_for(json_output),
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "trash.purge",
+            "entry_id": entry_id,
+        },
+        action=lambda: no_content_payload(
+            "trash.purged",
+            client_for().purge_trash_entry(
+                resolve_workspace_id(workspace_id),
+                entry_id,
+            ),
+        ),
+    )
+
+
+@trash_app.command("discard")
+def trash_discard(
+    entry_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    return destructive_action(
+        json_for(json_output),
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "trash.discard",
+            "entry_id": entry_id,
+        },
+        action=lambda: no_content_payload(
+            "trash.discarded",
+            client_for().discard_trash_entry(
+                resolve_workspace_id(workspace_id),
+                entry_id,
+            ),
+        ),
+    )
+
+
+@item_app.command("export")
+def item_export(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    query: str | None = typer.Option(None, "--query", help="Search title."),
+    available: bool = typer.Option(
+        False,
+        "--available",
+        help="Filter available items.",
+    ),
+    unavailable: bool = typer.Option(
+        False,
+        "--unavailable",
+        help="Filter unavailable items.",
+    ),
+    locked: bool = typer.Option(False, "--locked", help="Filter locked items."),
+    unlocked: bool = typer.Option(False, "--unlocked", help="Filter unlocked items."),
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    unclassified: bool = typer.Option(False, "--unclassified"),
+    page_size: int = typer.Option(100, "--page-size", min=1, max=100),
+    jsonl: bool = typer.Option(False, "--jsonl", help="Output one item per line."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    is_available = resolve_bool_filter(
+        positive=available,
+        negative=unavailable,
+        positive_name="--available",
+        negative_name="--unavailable",
+        json_output=json_enabled,
+    )
+    if type(is_available) is int:
+        return is_available
+    is_locked = resolve_bool_filter(
+        positive=locked,
+        negative=unlocked,
+        positive_name="--locked",
+        negative_name="--unlocked",
+        json_output=json_enabled,
+    )
+    if type(is_locked) is int:
+        return is_locked
+
+    def action() -> dict[str, Any]:
+        items = collect_items(
+            workspace_id=resolve_workspace_id(workspace_id),
+            query=query,
+            is_available=is_available,
+            is_locked=is_locked,
+            kb_id=kb_id,
+            folder_id=folder_id,
+            unclassified=unclassified,
+            page_size=page_size,
+        )
+        return {"items": items, "total": len(items)}
+
+    if not jsonl:
+        return run_cli_action(json_enabled, action)
+
+    try:
+        for item in action()["items"]:
+            print(json.dumps(item, ensure_ascii=False, sort_keys=True))
+    except CliAPIError as exc:
+        emit_cli_error(True, exc)
+        return exit_code_for_api_error(exc)
+    return EXIT_SUCCESS
+
+
+@item_app.command("import")
+def item_import(
+    path: Path,
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm write action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    if folder_id and not kb_id:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "--folder requires --kb.",
+        )
+    if not dry_run and not yes:
+        return emit_usage_error(
+            json_enabled,
+            "confirmation.required",
+            "Pass --yes to import items or use --dry-run.",
+        )
+    rows_or_error = read_import_rows(path, json_enabled)
+    if isinstance(rows_or_error, int):
+        return rows_or_error
+    payloads_or_error = import_payloads(
+        rows_or_error,
+        kb_id=kb_id,
+        folder_id=folder_id,
+        json_output=json_enabled,
+    )
+    if isinstance(payloads_or_error, int):
+        return payloads_or_error
+    if dry_run:
+        _emit(
+            {
+                "status": "dry_run",
+                "items": payloads_or_error,
+                "total": len(payloads_or_error),
+            },
+            json_enabled,
+        )
+        return EXIT_SUCCESS
+
+    def action() -> dict[str, Any]:
+        workspace = resolve_workspace_id(workspace_id)
+        client = client_for()
+        created = [
+            client.create_item(workspace, payload) for payload in payloads_or_error
+        ]
+        return {"status": "ok", "items": created, "total": len(created)}
+
+    return run_cli_action(json_enabled, action)
+
+
+@file_app.command("upload")
+def file_upload(
+    path: Path,
+    title: str | None = typer.Option(None, "--title"),
+    kb_id: str | None = typer.Option(None, "--kb"),
+    folder_id: str | None = typer.Option(None, "--folder"),
+    relation_type: str = typer.Option("primary", "--relation-type"),
+    pipeline_id: str | None = typer.Option(None, "--pipeline-id"),
+    metadata: Annotated[list[str] | None, typer.Option("--metadata")] = None,
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    validation = validate_file_command(
+        path=path,
+        relation_type=relation_type,
+        folder_id=folder_id,
+        kb_id=kb_id,
+        json_output=json_enabled,
+    )
+    if validation is not None:
+        return validation
+    parsed_metadata = parse_metadata_options(metadata, json_enabled)
+    if isinstance(parsed_metadata, int):
+        return parsed_metadata
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().upload_knowledge_item(
+            workspace,
+            path=path,
+            title=title,
+            kb_id=kb_id,
+            folder_id=folder_id,
+            relation_type=relation_type,
+            pipeline_id=pipeline_id,
+            metadata=parsed_metadata,
+            idempotency_key=idempotency_key,
+        ),
+    )
+
+
+@file_app.command("add")
+def file_add(
+    item_id: str,
+    path: Path,
+    relation_type: str = typer.Option("attachment", "--relation-type"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    validation = validate_file_command(
+        path=path,
+        relation_type=relation_type,
+        folder_id=None,
+        kb_id=None,
+        json_output=json_enabled,
+    )
+    if validation is not None:
+        return validation
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().add_file(
+            workspace,
+            item_id,
+            path=path,
+            relation_type=relation_type,
+            idempotency_key=idempotency_key,
+        ),
+    )
+
+
+@file_app.command("list")
+def file_list(
+    item_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_files(workspace, item_id),
+        text_renderer=render_file_list,
+    )
+
+
+@file_app.command("download")
+def file_download(
+    file_id: str,
+    output: Annotated[Path | None, typer.Option("--output")] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+
+    def action() -> dict[str, Any]:
+        target = output or Path(file_id)
+        content = client_for().download_file(
+            workspace,
+            file_id,
+        )
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+        return {"status": "ok", "path": str(target), "bytes": len(content)}
+
+    return run_cli_action(json_enabled, action)
+
+
+@file_app.command("preview")
+def file_preview(
+    file_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().preview_file(workspace, file_id),
+    )
+
+
+@file_app.command("read")
+def file_read(
+    file_id: str,
+    format_: str = typer.Option("text", "--format"),
+    range_: str | None = typer.Option(None, "--range"),
+    source: str = typer.Option("auto", "--source"),
+    max_chars: int | None = typer.Option(None, "--max-chars", min=1),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().read_file(
+            workspace,
+            file_id,
+            format_=format_,
+            range_=range_,
+            source=source,
+            max_chars=max_chars,
+        ),
+    )
+
+
+@file_app.command("delete")
+def file_delete(
+    item_id: str,
+    file_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output machine-readable JSON.",
+    ),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "file.delete",
+            "item_id": item_id,
+            "file_id": file_id,
+        },
+        action=lambda: no_content_payload(
+            "file.deleted",
+            delete_file_action(
+                workspace_id=workspace,
+                item_id=item_id,
+                file_id=file_id,
+            ),
+        ),
+    )
+
+
+@pipeline_app.command("list")
+def pipeline_list(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_pipelines(workspace),
+        text_renderer=render_pipeline_list,
+    )
+
+
+@pipeline_app.command("create")
+def pipeline_create(
+    name: str = typer.Option(..., "--name"),
+    goal: str = typer.Option("semantic_search", "--goal"),
+    config: str | None = typer.Option(None, "--config"),
+    is_default: bool = typer.Option(False, "--default"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if goal not in {"storage_only", "semantic_search", "semantic_search_plus"}:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "--goal must be storage_only, semantic_search or semantic_search_plus.",
+        )
+    parsed_config = parse_json_object(config, json_enabled)
+    if isinstance(parsed_config, int):
+        return parsed_config
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().create_pipeline(
+            workspace,
+            name=name,
+            goal=goal,
+            config=parsed_config or {},
+            is_default=is_default,
+        ),
+    )
+
+
+@pipeline_app.command("get")
+def pipeline_get(
+    pipeline_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_pipeline(workspace, pipeline_id),
+    )
+
+
+@pipeline_app.command("update")
+def pipeline_update(
+    pipeline_id: str,
+    name: str | None = typer.Option(None, "--name"),
+    goal: str | None = typer.Option(None, "--goal"),
+    config: str | None = typer.Option(None, "--config"),
+    set_default: bool = typer.Option(False, "--default"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if goal is not None and goal not in {
+        "storage_only",
+        "semantic_search",
+        "semantic_search_plus",
+    }:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "--goal must be storage_only, semantic_search or semantic_search_plus.",
+        )
+    parsed_config = parse_json_object(config, json_enabled)
+    if isinstance(parsed_config, int):
+        return parsed_config
+    payload = compact_payload(
+        {
+            "name": name,
+            "goal": goal,
+            "config": parsed_config,
+            "is_default": True if set_default else None,
+        }
+    )
+    if not payload:
+        return emit_usage_error(
+            json_enabled,
+            "pipeline.update_requires_change",
+            "Provide --name, --goal, --config or --default.",
+        )
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().update_pipeline(workspace, pipeline_id, payload),
+    )
+
+
+@pipeline_app.command("delete")
+def pipeline_delete(
+    pipeline_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: no_content_payload(
+            "pipeline.deleted",
+            client_for().delete_pipeline(workspace, pipeline_id),
+        ),
+    )
+
+
+@processing_app.command("trigger")
+def processing_trigger(
+    item_id: str,
+    pipeline_id: str | None = typer.Option(
+        None,
+        "--pipeline-id",
+        help="Must match the item's current pipeline_id; not a temporary override.",
+    ),
+    reason: str = typer.Option("manual", "--reason"),
+    idempotency_key: str | None = typer.Option(None, "--idempotency-key"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    effective_idempotency_key = idempotency_key or (
+        f"processing-trigger-{secrets.token_urlsafe(18)}"
+    )
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().trigger_processing(
+            workspace,
+            item_id,
+            pipeline_id=pipeline_id,
+            reason=reason,
+            idempotency_key=effective_idempotency_key,
+        ),
+    )
+
+
+@processing_app.command("status")
+def processing_status(
+    item_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_processing_runs(workspace, item_id),
+        text_renderer=render_processing_runs,
+    )
+
+
+@processing_app.command("get")
+def processing_get(
+    run_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_processing_run(workspace, run_id),
+    )
+
+
+@processing_app.command("retry")
+def processing_retry(
+    run_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().retry_processing_run(workspace, run_id),
+    )
+
+
+@processing_app.command("cancel")
+def processing_cancel(
+    run_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().cancel_processing_run(workspace, run_id),
+    )
+
+
+@processing_app.command("reconcile")
+def processing_reconcile(
+    status: Annotated[list[str] | None, typer.Option("--status")] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    statuses = status or ["pending", "running", "cancelling", "cancel_failed"]
+    allowed = {
+        "pending",
+        "running",
+        "cancelling",
+        "done",
+        "cancelled",
+        "cancel_failed",
+        "failed",
+    }
+    invalid = set(statuses) - allowed
+    if invalid:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "--status must be one of: pending, running, cancelling, done, "
+            "cancelled, cancel_failed or failed.",
+        )
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().reconcile_processing_runs(workspace, status=statuses),
+        text_renderer=render_processing_reconcile,
+    )
+
+
+@search_app.command("grep")
+def search_grep(
+    query: str,
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: with_search_suggestions(
+            client_for().search_grep(
+                workspace,
+                query=query,
+                page=page,
+                page_size=page_size,
+            ),
+            workspace_id=workspace,
+            command="search grep",
+        ),
+        text_renderer=render_search_list,
+    )
+
+
+@search_app.command("advanced")
+def search_advanced(
+    query: str | None = typer.Option(None, "--query"),
+    kb_id: Annotated[list[str] | None, typer.Option("--kb-id")] = None,
+    folder_id: str | None = typer.Option(None, "--folder-id"),
+    locked: bool = typer.Option(False, "--locked", help="Filter locked items."),
+    unlocked: bool = typer.Option(False, "--unlocked", help="Filter unlocked items."),
+    mime_type: Annotated[list[str] | None, typer.Option("--mime-type")] = None,
+    metadata_json: str | None = typer.Option(None, "--metadata-json"),
+    sort: str = typer.Option("relevance", "--sort"),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(20, "--page-size", min=1, max=100),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if sort not in {"relevance", "updated_at_desc", "created_at_desc"}:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "--sort must be relevance, updated_at_desc or created_at_desc.",
+        )
+    is_locked = resolve_bool_filter(
+        positive=locked,
+        negative=unlocked,
+        positive_name="--locked",
+        negative_name="--unlocked",
+        json_output=json_enabled,
+    )
+    if type(is_locked) is int:
+        return is_locked
+    metadata = parse_json_array(metadata_json, json_enabled)
+    if isinstance(metadata, int):
+        return metadata
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    payload = {
+        "query": query,
+        "kb_ids": kb_id,
+        "folder_id": folder_id,
+        "is_locked": is_locked,
+        "mime_types": mime_type,
+        "metadata": metadata or [],
+        "sort": sort,
+        "page": page,
+        "page_size": page_size,
+    }
+    return run_cli_action(
+        json_enabled,
+        lambda: with_search_suggestions(
+            client_for().search_advanced(
+                workspace,
+                payload=compact_payload(payload),
+            ),
+            workspace_id=workspace,
+            command="search advanced",
+        ),
+        text_renderer=render_search_list,
+    )
+
+
+@search_app.command("semantic")
+def search_semantic(
+    query: str,
+    top_k: int = typer.Option(10, "--top-k", min=1, max=50),
+    kb_id: Annotated[list[str] | None, typer.Option("--kb-id")] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: with_search_suggestions(
+            client_for().search_semantic(
+                workspace,
+                query=query,
+                kb_ids=kb_id,
+                top_k=top_k,
+            ),
+            workspace_id=workspace,
+            command="search semantic",
+        ),
+        text_renderer=render_search_rows,
+    )
+
+
+@app.command("recall")
+def recall(
+    query: str,
+    top_k: int = typer.Option(10, "--top-k", min=1, max=50),
+    kb_id: Annotated[list[str] | None, typer.Option("--kb-id")] = None,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: with_search_suggestions(
+            client_for().search_semantic(
+                workspace,
+                query=query,
+                kb_ids=kb_id,
+                top_k=top_k,
+                recall=True,
+            ),
+            workspace_id=workspace,
+            command="recall",
+        ),
+        text_renderer=render_search_rows,
+    )
+
+
+@chunk_app.command("get")
+def chunk_get(
+    file_id: str,
+    chunk_idx: int = typer.Option(..., "--chunk", min=0),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_chunk(workspace, file_id, chunk_idx),
+        text_renderer=render_chunk,
+    )
+
+
+@chunk_app.command("context")
+def chunk_context(
+    file_id: str,
+    chunk_idx: int = typer.Option(..., "--chunk", min=0),
+    window: int = typer.Option(1, "--window", min=0, max=10),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_chunk_context(
+            workspace,
+            file_id,
+            chunk_idx,
+            window=window,
+        ),
+        text_renderer=render_chunk_context,
+    )
+
+
+@source_app.command("locate")
+def source_locate(
+    file_id: str,
+    chunk_idx: int = typer.Option(..., "--chunk", min=0),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().locate_source(workspace, file_id, chunk_idx),
+        text_renderer=render_source_location,
+    )
+
+
+@source_app.command("expand")
+def source_expand(
+    file_id: str,
+    chunk_idx: int = typer.Option(..., "--chunk", min=0),
+    mode: str = typer.Option("page", "--mode"),
+    window: int = typer.Option(3, "--window", min=0, max=50),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if mode not in {"before", "after", "page"}:
+        return emit_usage_error(
+            json_enabled,
+            "cli.invalid_source_mode",
+            "source expand --mode must be one of: before, after, page.",
+        )
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().expand_source(
+            workspace,
+            file_id,
+            chunk_idx,
+            mode=mode,
+            window=window,
+        ),
+        text_renderer=render_source_expand,
+    )
+
+
+@source_app.command("page")
+def source_page(
+    file_id: str,
+    page_index: int = typer.Option(..., "--page-index", min=0),
+    include_image: bool = typer.Option(False, "--include-image/--no-include-image"),
+    include_bytes: bool = typer.Option(
+        False,
+        "--include-bytes/--no-include-bytes",
+        help="Include PNG base64 for Agent vision (sets include_image).",
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write rendered PNG to this path (implies image fetch).",
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+    max_width: int = typer.Option(1200, "--max-width", min=64, max=4096),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    want_bytes = include_bytes or output is not None
+    return run_cli_action(
+        json_enabled,
+        lambda: enrich_source_image_for_agent(
+            client_for().read_source_page(
+                workspace,
+                file_id,
+                page_index,
+                include_image=include_image or want_bytes,
+                max_width=max_width,
+                include_bytes=want_bytes,
+            ),
+            output_path=output,
+        ),
+        text_renderer=render_source_page,
+    )
+
+
+@source_app.command("region-image")
+def source_region_image(
+    file_id: str,
+    page_index: int = typer.Option(..., "--page-index", min=0),
+    bbox: str = typer.Option(..., "--bbox", help="PDF points: x1,y1,x2,y2."),
+    include_bytes: bool = typer.Option(
+        True,
+        "--include-bytes/--no-include-bytes",
+        help="Include PNG base64 for Agent vision (default: true).",
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write rendered PNG to this path.",
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+    max_width: int = typer.Option(1200, "--max-width", min=64, max=4096),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    parsed_bbox = parse_bbox_option(bbox)
+    if parsed_bbox is None:
+        return emit_usage_error(
+            json_enabled,
+            "cli.invalid_bbox",
+            "--bbox must be four numeric PDF point coordinates: x1,y1,x2,y2.",
+        )
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    want_bytes = include_bytes or output is not None
+    return run_cli_action(
+        json_enabled,
+        lambda: enrich_source_image_for_agent(
+            client_for().read_region_image(
+                workspace,
+                file_id,
+                page_index=page_index,
+                bbox=parsed_bbox,
+                max_width=max_width,
+                include_bytes=want_bytes,
+            ),
+            output_path=output,
+        ),
+        text_renderer=render_source_region_image,
+    )
+
+
+@mcp_app.command("list")
+def mcp_list(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_mcp_interfaces(workspace),
+        text_renderer=render_mcp_interfaces,
+    )
+
+
+@mcp_app.command("create")
+def mcp_create(
+    name: str = typer.Option(..., "--name"),
+    slug: str = typer.Option(..., "--slug"),
+    description: str | None = typer.Option(None, "--description"),
+    prompt_template: str | None = typer.Option(None, "--prompt-template"),
+    tool: Annotated[list[str] | None, typer.Option("--tool")] = None,
+    kb_id: Annotated[list[str] | None, typer.Option("--kb-id")] = None,
+    auth_type: str = typer.Option("api_key", "--auth-type"),
+    enabled: bool = typer.Option(False, "--enabled"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    payload_or_error = mcp_payload(
+        name=name,
+        description=description,
+        prompt_template=prompt_template,
+        tool=tool,
+        kb_id=kb_id,
+        auth_type=auth_type,
+        enabled=enabled,
+        json_output=json_enabled,
+    )
+    if isinstance(payload_or_error, int):
+        return payload_or_error
+    payload_or_error["slug"] = slug
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().create_mcp_interface(workspace, payload_or_error),
+    )
+
+
+@mcp_app.command("get")
+def mcp_get(
+    mcp_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_mcp_interface(workspace, mcp_id),
+    )
+
+
+@mcp_app.command("update")
+def mcp_update(
+    mcp_id: str,
+    name: str | None = typer.Option(None, "--name"),
+    description: str | None = typer.Option(None, "--description"),
+    prompt_template: str | None = typer.Option(None, "--prompt-template"),
+    tool: Annotated[list[str] | None, typer.Option("--tool")] = None,
+    kb_id: Annotated[list[str] | None, typer.Option("--kb-id")] = None,
+    auth_type: str | None = typer.Option(None, "--auth-type"),
+    enable: bool = typer.Option(False, "--enable"),
+    disable: bool = typer.Option(False, "--disable"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if enable and disable:
+        return emit_usage_error(
+            json_enabled,
+            "validation.invalid",
+            "Use either --enable or --disable.",
+        )
+    payload = compact_payload(
+        {
+            "name": name,
+            "description": description,
+            "prompt_template": prompt_template,
+            "enabled_tools": tool,
+            "kb_ids": kb_id,
+            "auth_type": auth_type,
+            "enabled": True if enable else False if disable else None,
+        }
+    )
+    if not payload:
+        return emit_usage_error(
+            json_enabled,
+            "mcp.update_requires_change",
+            "Provide an MCP field or --enable/--disable.",
+        )
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().update_mcp_interface(workspace, mcp_id, payload),
+    )
+
+
+@mcp_app.command("enable")
+def mcp_enable(
+    mcp_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().enable_mcp_interface(workspace, mcp_id),
+    )
+
+
+@mcp_app.command("disable")
+def mcp_disable(
+    mcp_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().disable_mcp_interface(workspace, mcp_id),
+    )
+
+
+@mcp_app.command("delete")
+def mcp_delete(
+    mcp_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={"status": "dry_run", "action": "mcp.delete", "id": mcp_id},
+        action=lambda: no_content_payload(
+            "mcp.deleted",
+            client_for().delete_mcp_interface(workspace, mcp_id),
+        ),
+    )
+
+
+@mcp_key_app.command("list")
+def mcp_key_list(
+    mcp_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().list_mcp_api_keys(workspace, mcp_id),
+        text_renderer=render_mcp_api_keys,
+    )
+
+
+@mcp_key_app.command("create")
+def mcp_key_create(
+    mcp_id: str,
+    name: str | None = typer.Option(None, "--name"),
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().create_mcp_api_key(workspace, mcp_id, name=name),
+    )
+
+
+@mcp_key_app.command("revoke")
+def mcp_key_revoke(
+    mcp_id: str,
+    key_id: str,
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm destructive action."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload={
+            "status": "dry_run",
+            "action": "mcp.key.revoke",
+            "mcp_id": mcp_id,
+            "key_id": key_id,
+        },
+        action=lambda: no_content_payload(
+            "mcp.key.revoked",
+            client_for().revoke_mcp_api_key(workspace, mcp_id, key_id),
+        ),
+    )
+
+
+@vector_index_app.command("status")
+def vector_index_status(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    workspace = resolve_workspace_or_error(workspace_id, json_enabled)
+    if isinstance(workspace, int):
+        return workspace
+    return run_cli_action(
+        json_enabled,
+        lambda: client_for().get_vector_index_status(workspace),
+    )
+
+
+@vector_index_app.command("rebuild")
+def vector_index_rebuild(
+    workspace_id: str = typer.Option(..., "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm vector index rebuild."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload=lambda: client_for().rebuild_vector_index(
+            workspace_id,
+            dry_run=True,
+        ),
+        action=lambda: client_for().rebuild_vector_index(
+            workspace_id,
+            dry_run=False,
+        ),
+    )
+
+
+@gc_app.command("workspace")
+def gc_workspace(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    deleted_before: str | None = typer.Option(
+        None,
+        "--deleted-before",
+        help="Garbage collect deleted workspaces before this date or timestamp.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm physical cleanup."),
+    include_vectors: bool = typer.Option(True, "--include-vectors/--skip-vectors"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    if (workspace_id is None) == (deleted_before is None):
+        return emit_usage_error(
+            json_enabled,
+            "gc.workspace_target_required",
+            "Provide exactly one of --workspace-id or --deleted-before.",
+        )
+    if deleted_before is not None:
+        cutoff = parse_gc_cutoff(deleted_before, json_enabled)
+        if isinstance(cutoff, int):
+            return cutoff
+        return destructive_action(
+            json_enabled,
+            dry_run=dry_run,
+            yes=yes,
+            dry_run_payload=lambda: client_for().gc_workspaces_deleted_before(
+                deleted_before=cutoff,
+                dry_run=True,
+                include_vectors=include_vectors,
+            ),
+            action=lambda: client_for().gc_workspaces_deleted_before(
+                deleted_before=cutoff,
+                dry_run=False,
+                include_vectors=include_vectors,
+            ),
+        )
+
+    assert workspace_id is not None
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload=lambda: client_for().gc_workspace(
+            workspace_id,
+            dry_run=True,
+            include_vectors=include_vectors,
+        ),
+        action=lambda: client_for().gc_workspace(
+            workspace_id,
+            dry_run=False,
+            include_vectors=include_vectors,
+        ),
+    )
+
+
+@gc_app.command("mcp-logs")
+def gc_mcp_logs(
+    workspace_id: str | None = typer.Option(None, "--workspace-id"),
+    deleted_before: str | None = typer.Option(
+        None,
+        "--deleted-before",
+        help="Delete MCP call logs before this date or timestamp.",
+    ),
+    retention_days: int = typer.Option(
+        30,
+        "--retention-days",
+        min=1,
+        help="Retention window in days when --deleted-before is omitted.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm log cleanup."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    cutoff = (
+        parse_gc_cutoff(deleted_before, json_enabled)
+        if deleted_before is not None
+        else (datetime.now(UTC) - timedelta(days=retention_days)).isoformat()
+    )
+    if isinstance(cutoff, int):
+        return cutoff
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload=lambda: client_for().gc_mcp_call_logs(
+            workspace_id=workspace_id,
+            deleted_before=cutoff,
+            dry_run=True,
+        ),
+        action=lambda: client_for().gc_mcp_call_logs(
+            workspace_id=workspace_id,
+            deleted_before=cutoff,
+            dry_run=False,
+        ),
+    )
+
+
+@gc_app.command("item")
+def gc_item(
+    item_id: str,
+    workspace_id: str = typer.Option(..., "--workspace-id"),
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    yes: bool = typer.Option(False, "--yes", help="Confirm physical cleanup."),
+    include_vectors: bool = typer.Option(True, "--include-vectors/--skip-vectors"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> int:
+    json_enabled = json_for(json_output)
+    return destructive_action(
+        json_enabled,
+        dry_run=dry_run,
+        yes=yes,
+        dry_run_payload=lambda: client_for().gc_item(
+            workspace_id,
+            item_id,
+            dry_run=True,
+            include_vectors=include_vectors,
+        ),
+        action=lambda: client_for().gc_item(
+            workspace_id,
+            item_id,
+            dry_run=False,
+            include_vectors=include_vectors,
+        ),
+    )
+
+
+def auth_login_action(
+    *,
+    email: str | None,
+    method: str,
+    password: str | None,
+    display_name: str | None,
+    no_browser: bool,
+    timeout_seconds: int,
+    json_output: bool,
+    store: StateStore,
+    state: CliState,
+    client: CortexClient,
+) -> dict[str, Any]:
+    if email is not None:
+        payload = client.debug_login(
+            email=email,
+            password=password,
+            display_name=display_name,
+        )
+    elif method == "device":
+        payload = device_login(
+            client=client,
+            no_browser=no_browser,
+            timeout_seconds=timeout_seconds,
+            json_output=json_output,
+        )
+    elif method == "loopback":
+        payload = feishu_loopback_login(
+            client=client,
+            no_browser=no_browser,
+            timeout_seconds=timeout_seconds,
+            json_output=json_output,
+        )
+    else:
+        raise CliAPIError(
+            code="cli.invalid_login_method",
+            message="Login method must be device or loopback.",
+            status_code=400,
+        )
+    state.access_token = payload["access_token"]
+    state.refresh_token = payload["refresh_token"]
+    store.save(state)
+    return {
+        "status": "ok",
+        "api_url": state.api_url,
+        "user": payload["user"],
+    }
+
+
+def device_login(
+    *,
+    client: CortexClient,
+    no_browser: bool,
+    timeout_seconds: int,
+    json_output: bool,
+) -> dict[str, Any]:
+    start = client.device_login_start()
+    verification_uri_complete = str(start["verification_uri_complete"])
+    user_code = str(start["user_code"])
+    device_code = str(start["device_code"])
+    interval = int(start.get("interval") or 2)
+
+    if not json_output:
+        print("Open this URL to login:", file=sys.stderr)
+        print(verification_uri_complete, file=sys.stderr)
+        print(f"Code: {user_code}", file=sys.stderr)
+    if not no_browser:
+        webbrowser.open(verification_uri_complete)
+
+    deadline = time.monotonic() + timeout_seconds
+    while True:
+        if time.monotonic() >= deadline:
+            raise CliAPIError(
+                code="auth.login_timeout",
+                message="Timed out waiting for browser authorization.",
+                status_code=408,
+            )
+        try:
+            return client.device_login_token(device_code=device_code)
+        except CliAPIError as exc:
+            if exc.code != "auth.authorization_pending":
+                raise
+        time.sleep(interval)
+
+
+def feishu_loopback_login(
+    *,
+    client: CortexClient,
+    no_browser: bool,
+    timeout_seconds: int,
+    json_output: bool,
+) -> dict[str, Any]:
+    cli_state = secrets.token_urlsafe(24)
+    code_verifier = secrets.token_urlsafe(48)
+    code_challenge = pkce_s256_challenge(code_verifier)
+
+    server = OAuthCallbackServer(("127.0.0.1", 0), OAuthCallbackHandler)
+    cli_redirect_uri = f"http://127.0.0.1:{server.server_port}/callback"
+
+    authorize = client.feishu_cli_authorize(
+        cli_redirect_uri=cli_redirect_uri,
+        state=cli_state,
+        code_challenge=code_challenge,
+    )
+    authorization_url = str(authorize["authorization_url"])
+
+    if no_browser:
+        if not json_output:
+            print(f"Open this URL to login:\n{authorization_url}", file=sys.stderr)
+    else:
+        webbrowser.open(authorization_url)
+
+    deadline = time.monotonic() + timeout_seconds
+    while server.callback_query is None:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise CliAPIError(
+                code="auth.login_timeout",
+                message="Timed out waiting for Feishu OAuth callback.",
+                status_code=408,
+            )
+        server.socket.settimeout(remaining)
+        try:
+            server.handle_request()
+        except OSError:
+            continue
+
+    returned_state = first_query_value(server.callback_query, "state")
+    cli_auth_code = first_query_value(server.callback_query, "cli_auth_code")
+    if returned_state != cli_state or cli_auth_code is None:
+        raise CliAPIError(
+            code="auth.oauth_callback_invalid",
+            message="OAuth callback state or code is invalid.",
+            status_code=400,
+        )
+
+    return client.feishu_cli_token(
+        cli_auth_code=cli_auth_code,
+        code_verifier=code_verifier,
+    )
+
+
+class OAuthCallbackServer(HTTPServer):
+    callback_query: dict[str, list[str]] | None = None
+
+
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_error(404)
+            return
+        self.server.callback_query = parse_qs(parsed.query)  # type: ignore[attr-defined]
+        body = b"Cortex CLI login completed. You can close this window."
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, _format: str, *_args: object) -> None:
+        return
+
+
+def pkce_s256_challenge(code_verifier: str) -> str:
+    digest = sha256(code_verifier.encode("ascii")).digest()
+    return urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def first_query_value(query: dict[str, list[str]], key: str) -> str | None:
+    values = query.get(key)
+    return values[0] if values else None
+
+
+def compact_payload(
+    payload: dict[str, Any],
+    *,
+    force_keys: set[str] | None = None,
+) -> dict[str, Any]:
+    forced = force_keys or set()
+    return {
+        key: value
+        for key, value in payload.items()
+        if value is not None or key in forced
+    }
+
+
+def resolve_bool_filter(
+    *,
+    positive: bool,
+    negative: bool,
+    positive_name: str,
+    negative_name: str,
+    json_output: bool,
+) -> bool | None | int:
+    if positive and negative:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            f"Use either {positive_name} or {negative_name}.",
+        )
+    if positive:
+        return True
+    if negative:
+        return False
+    return None
+
+
+def parse_bool_cell(
+    value: str | None,
+    *,
+    default: bool,
+    field: str,
+    json_output: bool,
+) -> bool | int:
+    if value is None or not value.strip():
+        return default
+    normalized = value.strip().casefold()
+    if normalized in {"true", "1", "yes", "y"}:
+        return True
+    if normalized in {"false", "0", "no", "n"}:
+        return False
+    return emit_usage_error(
+        json_output,
+        "validation.invalid_bool",
+        f"{field} must be true or false.",
+    )
+
+
+def parse_json_object(
+    value: str | None,
+    json_output: bool,
+) -> dict[str, Any] | None | int:
+    if value is None:
+        return None
+    try:
+        payload = json.loads(value)
+    except json.JSONDecodeError:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid_json",
+            "JSON value is invalid.",
+        )
+    if not isinstance(payload, dict):
+        return emit_usage_error(
+            json_output,
+            "validation.invalid_json",
+            "JSON value must be an object.",
+        )
+    return payload
+
+
+def parse_json_array(
+    value: str | None,
+    json_output: bool,
+) -> list[Any] | None | int:
+    if value is None:
+        return None
+    try:
+        payload = json.loads(value)
+    except json.JSONDecodeError:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid_json",
+            "JSON value is invalid.",
+        )
+    if not isinstance(payload, list):
+        return emit_usage_error(
+            json_output,
+            "validation.invalid_json",
+            "JSON value must be an array.",
+        )
+    return payload
+
+
+def parse_metadata_options(
+    values: list[str] | None,
+    json_output: bool,
+) -> list[dict[str, Any]] | int:
+    entries: list[dict[str, Any]] = []
+    for raw in values or []:
+        if "=" not in raw:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_metadata",
+                "--metadata must use key=value or key:type=value.",
+            )
+        key_part, value = raw.split("=", 1)
+        key, separator, value_type = key_part.partition(":")
+        value_type = value_type if separator else "string"
+        key = key.strip()
+        if not key or value_type not in {"string", "time"}:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_metadata",
+                "Metadata type must be string or time.",
+            )
+        entries.append({"key": key, "value_type": value_type, "value": value})
+    return entries
+
+
+def parse_kb_order_options(
+    values: list[str] | None,
+    json_output: bool,
+) -> list[dict[str, Any]] | int:
+    entries: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for raw in values or []:
+        if ":" in raw:
+            kb_id, sort_order_text = raw.split(":", 1)
+        elif "=" in raw:
+            kb_id, sort_order_text = raw.split("=", 1)
+        else:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_kb_order",
+                "--kb-order must use <kb-id>:<sort-order>.",
+            )
+        kb_id = kb_id.strip()
+        sort_order_text = sort_order_text.strip()
+        if not kb_id:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_kb_order",
+                "--kb-order requires a knowledge base id.",
+            )
+        if kb_id in seen:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_kb_order",
+                "--kb-order cannot include the same knowledge base twice.",
+            )
+        try:
+            sort_order = int(sort_order_text)
+        except ValueError:
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_kb_order",
+                "--kb-order sort order must be an integer.",
+            )
+        seen.add(kb_id)
+        entries.append({"kb_id": kb_id, "sort_order": sort_order})
+    return entries
+
+
+def build_item_payload(
+    *,
+    title: str,
+    is_available: bool,
+    is_locked: bool,
+    pipeline_id: str | None,
+    processing_config: str | None,
+    metadata: list[str] | None,
+    kb_id: str | None,
+    folder_id: str | None,
+    json_output: bool,
+) -> dict[str, Any] | int:
+    if folder_id and not kb_id:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            "--folder requires --kb.",
+        )
+    parsed_config = parse_json_object(processing_config, json_output)
+    if isinstance(parsed_config, int):
+        return parsed_config
+    parsed_metadata = parse_metadata_options(metadata, json_output)
+    if isinstance(parsed_metadata, int):
+        return parsed_metadata
+    payload: dict[str, Any] = {
+        "title": title,
+        "is_available": is_available,
+        "is_locked": is_locked,
+        "metadata": parsed_metadata,
+    }
+    if pipeline_id is not None:
+        payload["pipeline_id"] = pipeline_id
+    if parsed_config is not None:
+        payload["processing_config"] = parsed_config
+    if kb_id is not None:
+        payload["mount"] = {"kb_id": kb_id, "folder_id": folder_id}
+    return payload
+
+
+def mcp_payload(
+    *,
+    name: str,
+    description: str | None,
+    prompt_template: str | None,
+    tool: list[str] | None,
+    kb_id: list[str] | None,
+    auth_type: str,
+    enabled: bool,
+    json_output: bool,
+) -> dict[str, Any] | int:
+    tools = list(dict.fromkeys(tool or []))
+    kb_ids = list(dict.fromkeys(kb_id or []))
+    invalid_tools = set(tools) - MCP_TOOL_NAMES
+    if invalid_tools:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            "--tool contains unsupported MCP tools.",
+        )
+    if auth_type not in {"api_key", "none"}:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            "--auth-type must be api_key or none.",
+        )
+    return {
+        "name": name,
+        "description": description,
+        "prompt_template": prompt_template,
+        "enabled_tools": tools,
+        "kb_ids": kb_ids,
+        "auth_type": auth_type,
+        "enabled": enabled,
+    }
+
+
+def validate_file_command(
+    *,
+    path: Path,
+    relation_type: str,
+    folder_id: str | None,
+    kb_id: str | None,
+    json_output: bool,
+) -> int | None:
+    if not path.is_file():
+        return emit_usage_error(
+            json_output,
+            "file.not_found",
+            f"File does not exist: {path}",
+        )
+    if relation_type not in {"primary", "attachment"}:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            "--relation-type must be primary or attachment.",
+        )
+    if folder_id and not kb_id:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid",
+            "--folder requires --kb.",
+        )
+    return None
+
+
+def delete_file_action(*, workspace_id: str, item_id: str, file_id: str) -> None:
+    client = client_for()
+    try:
+        client.delete_file(workspace_id, item_id, file_id)
+    except CliAPIError as exc:
+        if exc.code != "resource.not_found":
+            raise
+        client.delete_file(workspace_id, file_id, item_id)
+
+
+def parse_gc_cutoff(value: str, json_output: bool) -> str | int:
+    try:
+        if "T" in value or " " in value:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        else:
+            parsed = datetime.combine(
+                date.fromisoformat(value),
+                datetime.min.time(),
+                tzinfo=UTC,
+            )
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=UTC)
+    except ValueError:
+        return emit_usage_error(
+            json_output,
+            "validation.invalid_datetime",
+            "--deleted-before must be an ISO date or timestamp.",
+        )
+    return parsed.astimezone(UTC).isoformat()
+
+
+def destructive_action(
+    json_output: bool,
+    *,
+    dry_run: bool,
+    yes: bool,
+    dry_run_payload: dict[str, Any] | Callable[[], Any],
+    action: Callable[[], Any],
+) -> int:
+    if dry_run:
+        if callable(dry_run_payload):
+            return run_cli_action(json_output, dry_run_payload)
+        _emit(dry_run_payload, json_output)
+        return EXIT_SUCCESS
+    if not yes:
+        return emit_usage_error(
+            json_output,
+            "confirmation.required",
+            "Pass --yes to execute this command or use --dry-run.",
+        )
+    return run_cli_action(json_output, action)
+
+
+def collect_items(
+    *,
+    workspace_id: str,
+    query: str | None,
+    is_available: bool | None,
+    is_locked: bool | None,
+    kb_id: str | None,
+    folder_id: str | None,
+    unclassified: bool,
+    page_size: int,
+) -> list[dict[str, Any]]:
+    client = client_for()
+    page = 1
+    items: list[dict[str, Any]] = []
+    while True:
+        payload = client.list_items(
+            workspace_id,
+            page=page,
+            page_size=page_size,
+            query=query,
+            is_available=is_available,
+            is_locked=is_locked,
+            kb_id=kb_id,
+            folder_id=folder_id,
+            unclassified=unclassified,
+        )
+        page_items = payload.get("items", [])
+        items.extend(page_items)
+        if len(items) >= int(payload.get("total") or 0) or len(page_items) < page_size:
+            return items
+        page += 1
+
+
+def with_search_suggestions(
+    payload: dict[str, Any] | list[dict[str, Any]],
+    *,
+    workspace_id: str,
+    command: str,
+) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        items = payload.get("items") if isinstance(payload.get("items"), list) else []
+        result = dict(payload)
+    else:
+        items = payload
+        result = {"items": payload}
+    result["next"] = search_next_steps(
+        [item for item in items if isinstance(item, dict)],
+        workspace_id=workspace_id,
+        command=command,
+    )
+    return result
+
+
+def search_next_steps(
+    items: list[dict[str, Any]],
+    *,
+    workspace_id: str,
+    command: str,
+) -> list[dict[str, str]]:
+    if not items:
+        return [
+            {
+                "label": "broaden_search",
+                "command": (
+                    f"cortex search advanced --workspace-id {workspace_id} --json"
+                ),
+            }
+        ]
+    steps: list[dict[str, str]] = []
+    for item in items[:3]:
+        item_id = item.get("item_id")
+        file_id = item.get("file_id")
+        chunk_idx = item.get("chunk_idx")
+        if item_id:
+            steps.append(
+                {
+                    "label": "inspect_item",
+                    "command": (
+                        f"cortex item get {item_id} "
+                        f"--workspace-id {workspace_id} --json"
+                    ),
+                }
+            )
+        if file_id and chunk_idx is not None:
+            steps.append(
+                {
+                    "label": "read_context",
+                    "command": (
+                        f"cortex chunk context {file_id} --chunk {chunk_idx} "
+                        f"--workspace-id {workspace_id} --json"
+                    ),
+                }
+            )
+        if file_id:
+            steps.append(
+                {
+                    "label": "read_file",
+                    "command": (
+                        f"cortex file read {file_id} "
+                        f"--workspace-id {workspace_id} --json"
+                    ),
+                }
+            )
+    if command != "recall":
+        steps.append(
+            {
+                "label": "recall_chunks",
+                "command": (
+                    f"cortex recall <query> --workspace-id {workspace_id} --json"
+                ),
+            }
+        )
+    return dedupe_next_steps(steps)
+
+
+def dedupe_next_steps(steps: list[dict[str, str]]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for step in steps:
+        command = step["command"]
+        if command in seen:
+            continue
+        seen.add(command)
+        result.append(step)
+    return result[:8]
+
+
+def read_import_rows(path: Path, json_output: bool) -> list[dict[str, str]] | int:
+    if not path.exists():
+        return emit_usage_error(
+            json_output,
+            "file.not_found",
+            f"Import file does not exist: {path}",
+        )
+    suffix = path.suffix.casefold()
+    if suffix == ".csv":
+        with path.open(newline="", encoding="utf-8-sig") as file:
+            return [
+                {key: value for key, value in row.items() if key is not None}
+                for row in csv.DictReader(file)
+            ]
+    if suffix == ".xlsx":
+        try:
+            return read_xlsx_rows(path)
+        except CliAPIError as exc:
+            emit_cli_error(json_output, exc)
+            return EXIT_USAGE
+        except (
+            ElementTree.ParseError,
+            KeyError,
+            ValueError,
+            zipfile.BadZipFile,
+        ):
+            return emit_usage_error(
+                json_output,
+                "validation.invalid_xlsx",
+                "XLSX file cannot be read.",
+            )
+    return emit_usage_error(
+        json_output,
+        "validation.unsupported_file",
+        "Import supports .csv and .xlsx files.",
+    )
+
+
+def import_payloads(
+    rows: list[dict[str, str]],
+    *,
+    kb_id: str | None,
+    folder_id: str | None,
+    json_output: bool,
+) -> list[dict[str, Any]] | int:
+    payloads: list[dict[str, Any]] = []
+    for index, row in enumerate(rows, start=2):
+        title = (row.get("title") or "").strip()
+        if not title:
+            return emit_usage_error(
+                json_output,
+                "validation.missing_title",
+                f"Row {index} is missing title.",
+            )
+        is_available = parse_bool_cell(
+            row.get("is_available"),
+            default=True,
+            field="is_available",
+            json_output=json_output,
+        )
+        if type(is_available) is int:
+            return is_available
+        is_locked = parse_bool_cell(
+            row.get("is_locked"),
+            default=False,
+            field="is_locked",
+            json_output=json_output,
+        )
+        if type(is_locked) is int:
+            return is_locked
+        processing_config = (
+            row.get("processing_config_json") or row.get("processing_config") or None
+        )
+        metadata_options = row_metadata_options(row)
+        payload = build_item_payload(
+            title=title,
+            is_available=is_available,
+            is_locked=is_locked,
+            pipeline_id=(row.get("pipeline_id") or None),
+            processing_config=processing_config,
+            metadata=metadata_options,
+            kb_id=kb_id,
+            folder_id=folder_id,
+            json_output=json_output,
+        )
+        if isinstance(payload, int):
+            return payload
+        payloads.append(payload)
+    return payloads
+
+
+def row_metadata_options(row: dict[str, str]) -> list[str]:
+    reserved = {
+        "title",
+        "is_available",
+        "is_locked",
+        "pipeline_id",
+        "processing_config_json",
+    }
+    reserved.add("processing_config")
+    result: list[str] = []
+    for key, value in row.items():
+        if key in reserved or value in (None, ""):
+            continue
+        metadata_key = key.removeprefix("metadata.")
+        result.append(f"{metadata_key}={value}")
+    return result
+
+
+def read_xlsx_rows(path: Path) -> list[dict[str, str]]:
+    with zipfile.ZipFile(path) as archive:
+        shared_strings = xlsx_shared_strings(archive)
+        sheet_path = xlsx_first_sheet_path(archive)
+        root = ElementTree.fromstring(archive.read(sheet_path))
+
+    rows: list[list[str]] = []
+    namespace = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
+    for row in root.findall(f".//{namespace}sheetData/{namespace}row"):
+        values: dict[int, str] = {}
+        for cell in row.findall(f"{namespace}c"):
+            ref = cell.attrib.get("r", "")
+            column = xlsx_column_index(ref)
+            values[column] = xlsx_cell_value(cell, shared_strings)
+        if values:
+            rows.append([values.get(index, "") for index in range(max(values) + 1)])
+
+    if not rows:
+        return []
+    headers = [header.strip() for header in rows[0]]
+    return [
+        {
+            headers[index]: value
+            for index, value in enumerate(row)
+            if index < len(headers) and headers[index]
+        }
+        for row in rows[1:]
+    ]
+
+
+def xlsx_shared_strings(archive: zipfile.ZipFile) -> list[str]:
+    try:
+        root = ElementTree.fromstring(archive.read("xl/sharedStrings.xml"))
+    except KeyError:
+        return []
+    namespace = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
+    strings: list[str] = []
+    for item in root.findall(f"{namespace}si"):
+        strings.append("".join(node.text or "" for node in item.iter(f"{namespace}t")))
+    return strings
+
+
+def xlsx_first_sheet_path(archive: zipfile.ZipFile) -> str:
+    package_rel = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+    spreadsheet = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
+    workbook = ElementTree.fromstring(archive.read("xl/workbook.xml"))
+    first_sheet = workbook.find(f".//{spreadsheet}sheet")
+    if first_sheet is None:
+        raise CliAPIError(
+            code="validation.invalid_xlsx",
+            message="Workbook contains no sheets.",
+            status_code=400,
+        )
+    rel_id = first_sheet.attrib[
+        "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id"
+    ]
+    rels = ElementTree.fromstring(archive.read("xl/_rels/workbook.xml.rels"))
+    targets = {
+        rel.attrib["Id"]: rel.attrib["Target"]
+        for rel in rels.findall(f"{package_rel}Relationship")
+    }
+    target = targets[rel_id]
+    return f"xl/{target}" if not target.startswith("/") else target.removeprefix("/")
+
+
+def xlsx_column_index(cell_ref: str) -> int:
+    letters = "".join(char for char in cell_ref if char.isalpha())
+    index = 0
+    for char in letters:
+        index = index * 26 + (ord(char.upper()) - ord("A") + 1)
+    return max(index - 1, 0)
+
+
+def xlsx_cell_value(cell: ElementTree.Element, shared_strings: list[str]) -> str:
+    namespace = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
+    if cell.attrib.get("t") == "inlineStr":
+        return "".join(node.text or "" for node in cell.iter(f"{namespace}t"))
+    value = cell.find(f"{namespace}v")
+    if value is None or value.text is None:
+        return ""
+    if cell.attrib.get("t") == "s":
+        return shared_strings[int(value.text)]
+    return value.text
+
+
+def run_cli_action(
+    json_output: bool,
+    action: Callable[[], Any],
+    *,
+    text_renderer: Callable[[Any], None] | None = None,
+) -> int:
+    try:
+        payload = action()
+    except CliAPIError as exc:
+        emit_cli_error(json_output, exc)
+        return exit_code_for_api_error(exc)
+
+    if text_renderer is not None and not json_output:
+        text_renderer(payload)
+        return EXIT_SUCCESS
+    _emit(payload, json_output)
+    return EXIT_SUCCESS
+
+
+def exit_code_for_api_error(exc: CliAPIError) -> int:
+    if exc.status_code == 401:
+        return EXIT_AUTH
+    if exc.status_code == 403:
+        return EXIT_FORBIDDEN
+    if exc.status_code == 404:
+        return EXIT_NOT_FOUND
+    if exc.status_code == 409 or exc.code in {
+        "resource.conflict",
+        "resource.locked",
+        "idempotency.conflict",
+    }:
+        return EXIT_CONFLICT
+    if exc.status_code >= 500 or exc.status_code == 0:
+        return EXIT_ERROR
+    return EXIT_USAGE
+
+
+def client_for() -> CortexClient:
+    store = StateStore()
+    state = load_state(store)
+    return client_from_state(store, state)
+
+
+def client_from_state(store: StateStore, state: CliState) -> CortexClient:
+    def update_tokens(payload: dict[str, Any]) -> None:
+        state.access_token = payload["access_token"]
+        state.refresh_token = payload["refresh_token"]
+        store.save(state)
+
+    return CortexClient(
+        base_url=state.api_url,
+        access_token=state.access_token,
+        refresh_token=state.refresh_token,
+        token_updater=update_tokens,
+    )
+
+
+def doctor_api_check(name: str, action: Callable[[], Any]) -> dict[str, str]:
+    try:
+        payload = action()
+    except CliAPIError as exc:
+        return {
+            "name": name,
+            "status": "error",
+            "message": f"{exc.code}: {exc.message}",
+        }
+    status = payload.get("status") if isinstance(payload, dict) else None
+    expected = "ok" if name == "health" else "ready"
+    return {
+        "name": name,
+        "status": "ok" if status == expected else "error",
+        "message": str(status or "unexpected response"),
+    }
+
+
+def doctor_token_check(state: CliState, client: CortexClient) -> dict[str, str]:
+    if not state.access_token:
+        return {
+            "name": "token",
+            "status": "warn",
+            "message": "No local access token.",
+        }
+    try:
+        client.me()
+    except CliAPIError as exc:
+        return {
+            "name": "token",
+            "status": "error",
+            "message": f"{exc.code}: {exc.message}",
+        }
+    return {"name": "token", "status": "ok", "message": "Access token is valid."}
+
+
+def doctor_workspace_check(state: CliState, client: CortexClient) -> dict[str, str]:
+    if not state.default_workspace_id:
+        return {
+            "name": "default_workspace",
+            "status": "warn",
+            "message": "No default Workspace configured.",
+        }
+    if not state.access_token:
+        return {
+            "name": "default_workspace",
+            "status": "warn",
+            "message": "Cannot validate Workspace without an access token.",
+        }
+    try:
+        client.get_workspace(state.default_workspace_id)
+    except CliAPIError as exc:
+        return {
+            "name": "default_workspace",
+            "status": "error",
+            "message": f"{exc.code}: {exc.message}",
+        }
+    return {
+        "name": "default_workspace",
+        "status": "ok",
+        "message": state.default_workspace_id,
+    }
+
+
+def load_state(store: StateStore) -> CliState:
+    state = store.load()
+    if GLOBAL_API_URL:
+        state.api_url = GLOBAL_API_URL
+    elif not state.api_url:
+        state.api_url = default_api_url()
+    return state
+
+
+def resolve_workspace_id(workspace_id: str | None) -> str:
+    resolved = workspace_id or StateStore().load().default_workspace_id
+    if not resolved:
+        raise CliAPIError(
+            code="workspace.required",
+            message="Provide a workspace id or run `cortex workspace use <id>`.",
+            status_code=400,
+        )
+    return resolved
+
+
+def resolve_workspace_or_error(
+    workspace_id: str | None,
+    json_output: bool,
+) -> str | int:
+    try:
+        return resolve_workspace_id(workspace_id)
+    except CliAPIError as exc:
+        emit_cli_error(json_output, exc)
+        return exit_code_for_api_error(exc)
+
+
+def parse_bbox_option(value: str) -> list[float] | None:
+    parts = [part.strip() for part in value.split(",")]
+    if len(parts) != 4:
+        return None
+    try:
+        bbox = [float(part) for part in parts]
+    except ValueError:
+        return None
+    x1, y1, x2, y2 = bbox
+    if x2 <= x1 or y2 <= y1:
+        return None
+    return bbox
+
+
+def no_content_payload(status: str, _result: object) -> dict[str, str]:
+    return {"status": status}
+
+
+def trash_restore_target(
+    *,
+    kb_id: str | None,
+    folder_id: str | None,
+    item_id: str | None,
+    unclassified: bool,
+    original: bool,
+) -> dict[str, str]:
+    if original:
+        return {"kind": "original"}
+    if kb_id:
+        return {"kind": "kb_root", "kb_id": kb_id}
+    if folder_id:
+        return {"kind": "folder", "folder_id": folder_id}
+    if item_id:
+        return {"kind": "knowledge_item", "knowledge_item_id": item_id}
+    if unclassified:
+        return {"kind": "unclassified"}
+    raise CliAPIError(
+        code="trash.restore_target_required",
+        message="Provide a restore target.",
+        status_code=400,
+    )
+
+
+def emit_usage_error(json_output: bool, code: str, message: str) -> int:
+    emit_cli_error(
+        json_output,
+        CliAPIError(code=code, message=message, status_code=400),
+    )
+    return EXIT_USAGE
+
+
+def emit_cli_error(json_output: bool, exc: CliAPIError) -> None:
+    payload = {
+        "error": {
+            "code": exc.code,
+            "message": exc.message,
+            "details": exc.details,
+        }
+    }
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True), file=sys.stderr)
+        return
+    print(f"error: {exc.code}: {exc.message}", file=sys.stderr)
+
+
+def render_item_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["ID", "AVAIL", "LOCK", "MOUNTS", "TITLE"],
+        lambda item: [
+            short_id(item.get("id")),
+            bool_mark(item.get("is_available")),
+            bool_mark(item.get("is_locked")),
+            str(len(item.get("mounts") or [])),
+            str(item.get("title") or ""),
+        ],
+        empty_message="No knowledge items.",
+    )
+
+
+def render_trash_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["ID", "TYPE", "STATUS", "LOCATION", "TITLE"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("object_type") or "-"),
+            trash_status_label(item),
+            trash_location_label(item),
+            str(item.get("title") or ""),
+        ],
+        empty_message="No trash entries.",
+    )
+
+
+def trash_status_label(item: dict[str, Any]) -> str:
+    original_location = item.get("original_location")
+    if isinstance(original_location, dict):
+        return str(original_location.get("status") or "-")
+    return "-"
+
+
+def trash_location_label(item: dict[str, Any]) -> str:
+    original_location = item.get("original_location")
+    if isinstance(original_location, dict) and original_location.get("label"):
+        return str(original_location["label"])
+    return "-"
+
+
+def render_workspace_panel(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    user = payload.get("user") or {}
+    if isinstance(user, dict):
+        display = user.get("display_name") or user.get("email") or user.get("id") or "-"
+        print(f"User: {display}")
+    workspaces = payload.get("workspaces")
+    invites = payload.get("pending_invites")
+    if isinstance(workspaces, list):
+        print("Workspaces")
+        render_sequence_table(
+            workspaces,
+            ["ID", "ROLE", "NAME", "OWNER"],
+            lambda item: [
+                short_id(item.get("id")),
+                str(item.get("role") or "-"),
+                str(item.get("name") or ""),
+                short_id(item.get("owner_id")),
+            ],
+            empty_message="No workspaces.",
+        )
+    if isinstance(invites, list):
+        print("Pending invites")
+        render_sequence_table(
+            invites,
+            ["ID", "ROLE", "WORKSPACE", "INVITED_BY"],
+            lambda item: [
+                short_id(item.get("id")),
+                str(item.get("role") or "-"),
+                str(item.get("workspace_name") or ""),
+                str(item.get("invited_by_name") or "-"),
+            ],
+            empty_message="No pending invites.",
+        )
+
+
+def render_invite_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["ID", "STATUS", "ROLE", "EMAIL/WORKSPACE", "INVITED_BY"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("status") or "-"),
+            str(item.get("role") or "-"),
+            str(item.get("invite_email") or item.get("workspace_name") or ""),
+            str(item.get("invited_by_name") or "-"),
+        ],
+        empty_message="No invites.",
+    )
+
+
+def render_invite_link_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["ID", "STATE", "ROLE", "USES", "PREFIX", "NAME"],
+        lambda item: [
+            short_id(item.get("id")),
+            "revoked" if item.get("revoked_at") else "active",
+            str(item.get("role") or "-"),
+            str(item.get("used_count") or 0),
+            str(item.get("token_prefix") or "-"),
+            str(item.get("name") or ""),
+        ],
+        empty_message="No invite links.",
+    )
+
+
+def render_invite_link_created(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"Invite link: {payload.get('invite_url')}")
+    print(f"Token: {payload.get('token')}")
+    print("The token is only shown once. Store or share this URL now.")
+
+
+def render_member_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["USER", "ROLE", "NAME", "EMAIL"],
+        lambda item: [
+            short_id(item.get("user_id")),
+            str(item.get("role") or "-"),
+            str(item.get("display_name") or ""),
+            str(item.get("email") or "-"),
+        ],
+        empty_message="No members.",
+    )
+
+
+def render_kb_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        ["ID", "POLICY", "EDIT", "PIPELINE", "NAME", "DESCRIPTION"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("edit_policy") or "-"),
+            "yes" if dict(item.get("capabilities") or {}).get("can_edit") else "no",
+            short_id(item.get("pipeline_id")),
+            str(item.get("name") or ""),
+            truncate(item.get("description"), 48),
+        ],
+        empty_message="No knowledge bases.",
+    )
+
+
+def render_kb_order(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    render_sequence_table(
+        payload.get("items") or [],
+        ["ID", "POLICY", "EDIT", "PIPELINE", "NAME", "DESCRIPTION"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("edit_policy") or "-"),
+            "yes" if dict(item.get("capabilities") or {}).get("can_edit") else "no",
+            short_id(item.get("pipeline_id")),
+            str(item.get("name") or ""),
+            truncate(item.get("description"), 48),
+        ],
+        empty_message="No knowledge bases.",
+    )
+
+
+def render_kb_permissions(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"KB: {short_id(payload.get('kb_id'))}")
+    print(f"Edit policy: {payload.get('edit_policy') or '-'}")
+    editors = payload.get("granted_editors") or []
+    render_sequence_table(
+        editors,
+        ["USER", "NAME", "EMAIL", "GRANTED_BY"],
+        lambda item: [
+            short_id(item.get("user_id")),
+            str(item.get("display_name") or ""),
+            str(item.get("email") or "-"),
+            short_id(item.get("granted_by")),
+        ],
+        empty_message="No granted editors.",
+    )
+
+
+def render_folder_tree(payload: Any) -> None:
+    if not isinstance(payload, list):
+        _emit(payload, json_output=False)
+        return
+    if not payload:
+        print("No folders.")
+        return
+    for line in folder_tree_lines(payload):
+        print(line)
+
+
+def render_file_list(payload: Any) -> None:
+    render_sequence_table(
+        payload,
+        ["ID", "REL", "PREVIEW", "SIZE", "NAME"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("relation_type") or "-"),
+            str(item.get("preview_status") or "-"),
+            format_bytes(item.get("file_size")),
+            str(item.get("file_name") or ""),
+        ],
+        empty_message="No files.",
+    )
+
+
+def render_pipeline_list(payload: Any) -> None:
+    render_sequence_table(
+        payload,
+        ["ID", "DEFAULT", "GOAL", "NAME"],
+        lambda item: [
+            short_id(item.get("id")),
+            bool_mark(item.get("is_default")),
+            str(item.get("goal") or "-"),
+            str(item.get("name") or ""),
+        ],
+        empty_message="No processing pipelines.",
+    )
+
+
+def render_processing_runs(payload: Any) -> None:
+    if isinstance(payload, dict) and isinstance(payload.get("items"), list):
+        render_paged_table(
+            payload,
+            ["ID", "STATUS", "STEP", "PIPELINE", "ERROR"],
+            lambda item: processing_run_row(item, run_id_field="id"),
+            empty_message="No processing runs.",
+        )
+        return
+    render_sequence_table(
+        payload,
+        ["ID", "STATUS", "STEP", "PIPELINE", "ERROR"],
+        lambda item: processing_run_row(item, run_id_field="id"),
+        empty_message="No processing runs.",
+    )
+
+
+def render_processing_reconcile(payload: Any) -> None:
+    render_sequence_table(
+        payload,
+        ["RUN", "OLD", "NEW", "TEMPORAL", "CHANGED", "ERROR"],
+        lambda item: [
+            short_id(item.get("run_id")),
+            str(item.get("old_status") or "-"),
+            str(item.get("new_status") or "-"),
+            str(item.get("temporal_status") or "-"),
+            bool_mark(item.get("changed")),
+            truncate(item.get("error"), 40),
+        ],
+        empty_message="No reconcile candidates.",
+    )
+
+
+def render_search_list(payload: Any) -> None:
+    render_paged_table(
+        payload,
+        search_headers(),
+        search_result_row,
+        empty_message="No search results.",
+    )
+    render_next_steps(payload)
+
+
+def render_search_rows(payload: Any) -> None:
+    rows = payload.get("items") if isinstance(payload, dict) else payload
+    render_sequence_table(
+        rows,
+        search_headers(),
+        search_result_row,
+        empty_message="No search results.",
+    )
+    render_next_steps(payload)
+
+
+def render_chunk(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"chunk: {payload.get('chunk_idx')}")
+    text = str(payload.get("text") or "")
+    if text:
+        print(text)
+
+
+def render_chunk_context(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"target_chunk: {payload.get('chunk_idx')}")
+    chunks = payload.get("chunks")
+    if not isinstance(chunks, list) or not chunks:
+        print("No chunks.")
+        return
+    for chunk in chunks:
+        if not isinstance(chunk, dict):
+            continue
+        print(f"--- chunk {chunk.get('chunk_idx')} ---")
+        print(str(chunk.get("text") or ""))
+
+
+def render_source_location(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"chunk: {payload.get('chunk_idx')}")
+    anchors = payload.get("anchors")
+    print(f"anchors: {len(anchors) if isinstance(anchors, list) else 0}")
+    regions = payload.get("regions")
+    print(f"regions: {len(regions) if isinstance(regions, list) else 0}")
+    artifact = payload.get("artifact")
+    if isinstance(artifact, dict):
+        print(f"artifact: {artifact.get('kind')} {short_id(artifact.get('id'))}")
+    blocks = payload.get("blocks")
+    if isinstance(blocks, list) and blocks:
+        for block in blocks:
+            if not isinstance(block, dict):
+                continue
+            print(f"--- block {block.get('block_id')} ---")
+            print(str(block.get("text") or ""))
+
+
+def render_source_expand(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"chunk: {payload.get('chunk_idx')}")
+    print(f"mode: {payload.get('mode')}")
+    print(f"window: {payload.get('window')}")
+    blocks = payload.get("blocks")
+    regions = payload.get("regions")
+    print(f"blocks: {len(blocks) if isinstance(blocks, list) else 0}")
+    print(f"regions: {len(regions) if isinstance(regions, list) else 0}")
+    text = str(payload.get("text") or "")
+    if text:
+        print(text)
+
+
+def render_source_page(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"page: {payload.get('page_label') or payload.get('page_index')}")
+    blocks = payload.get("blocks")
+    regions = payload.get("regions")
+    print(f"blocks: {len(blocks) if isinstance(blocks, list) else 0}")
+    print(f"regions: {len(regions) if isinstance(regions, list) else 0}")
+    image = payload.get("image")
+    if isinstance(image, dict):
+        print(f"image: {image.get('mime_type')} {image.get('object_name')}")
+        if image.get("data_base64"):
+            print(f"image_bytes: base64 len={len(str(image.get('data_base64')))}")
+        if payload.get("saved_image_path"):
+            print(f"saved: {payload.get('saved_image_path')}")
+    text = str(payload.get("text") or "")
+    if text:
+        print(text)
+
+
+def render_source_region_image(payload: Any) -> None:
+    if not isinstance(payload, dict):
+        _emit(payload, json_output=False)
+        return
+    print(f"file: {payload.get('file_id')}")
+    print(f"page_index: {payload.get('page_index')}")
+    print(f"bbox: {payload.get('bbox')}")
+    image = payload.get("image")
+    if isinstance(image, dict):
+        print(f"image: {image.get('mime_type')} {image.get('object_name')}")
+        if image.get("data_base64"):
+            print(f"image_bytes: base64 len={len(str(image.get('data_base64')))}")
+        if payload.get("saved_image_path"):
+            print(f"saved: {payload.get('saved_image_path')}")
+
+
+def enrich_source_image_for_agent(
+    payload: Any,
+    *,
+    output_path: Path | None = None,
+) -> Any:
+    """Attach MCP-aligned vision content and optionally write PNG for Agents.
+
+    JSON shape (when bytes present)::
+
+        {
+          "image": {..., "data_base64": "..."},
+          "content": [
+            {"type": "text", "text": "..."},
+            {"type": "image", "mimeType": "image/png", "data": "<base64>"}
+          ],
+          "saved_image_path": "/optional/path.png"
+        }
+
+    ``mimeType`` matches MCP resource spelling for schema-validating clients.
+    """
+    if not isinstance(payload, dict):
+        return payload
+
+    result = dict(payload)
+    image = result.get("image")
+    if not isinstance(image, dict):
+        return result
+
+    data_b64 = image.get("data_base64")
+    if isinstance(data_b64, str) and data_b64:
+        if output_path is not None:
+            raw = base64.b64decode(data_b64)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_bytes(raw)
+            result["saved_image_path"] = str(output_path.resolve())
+
+        text_parts: list[str] = []
+        page_label = result.get("page_label") or result.get("page_index")
+        if page_label is not None:
+            text_parts.append(f"page={page_label}")
+        if result.get("bbox") is not None:
+            text_parts.append(f"bbox={result.get('bbox')}")
+        body_text = str(result.get("text") or "").strip()
+        if body_text:
+            text_parts.append(body_text)
+        mime = str(image.get("mime_type") or image.get("mimeType") or "image/png")
+        result["content"] = [
+            {
+                "type": "text",
+                "text": "\n".join(text_parts) if text_parts else "source image",
+            },
+            {
+                "type": "image",
+                "mimeType": mime,
+                "data": data_b64,
+            },
+        ]
+    return result
+
+
+def render_mcp_interfaces(payload: Any) -> None:
+    render_sequence_table(
+        payload,
+        ["ID", "ENABLED", "AUTH", "KBS", "TOOLS", "SLUG", "NAME"],
+        lambda item: [
+            short_id(item.get("id")),
+            bool_mark(item.get("enabled")),
+            str(item.get("auth_type") or "-"),
+            str(len(item.get("kb_ids") or [])),
+            ",".join(item.get("enabled_tools") or []),
+            str(item.get("slug") or ""),
+            str(item.get("name") or ""),
+        ],
+        empty_message="No MCP interfaces.",
+    )
+
+
+def render_mcp_api_keys(payload: Any) -> None:
+    render_sequence_table(
+        payload,
+        ["ID", "PREFIX", "REVOKED", "EXPIRES", "NAME"],
+        lambda item: [
+            short_id(item.get("id")),
+            str(item.get("key_prefix") or "-"),
+            bool_mark(item.get("revoked_at") is not None),
+            str(item.get("expires_at") or "-"),
+            str(item.get("name") or ""),
+        ],
+        empty_message="No MCP API keys.",
+    )
+
+
+def render_next_steps(payload: Any) -> None:
+    if not isinstance(payload, dict) or not isinstance(payload.get("next"), list):
+        return
+    steps = [step for step in payload["next"] if isinstance(step, dict)]
+    if not steps:
+        return
+    print("Next:")
+    for step in steps:
+        label = step.get("label") or "next"
+        command = step.get("command") or ""
+        print(f"  {label}: {command}")
+
+
+def render_paged_table(
+    payload: Any,
+    headers: list[str],
+    row_builder: Callable[[dict[str, Any]], list[str]],
+    *,
+    empty_message: str,
+) -> None:
+    if not isinstance(payload, dict) or not isinstance(payload.get("items"), list):
+        _emit(payload, json_output=False)
+        return
+    render_sequence_table(
+        payload["items"],
+        headers,
+        row_builder,
+        empty_message=empty_message,
+    )
+    print(pagination_line(payload))
+
+
+def render_sequence_table(
+    payload: Any,
+    headers: list[str],
+    row_builder: Callable[[dict[str, Any]], list[str]],
+    *,
+    empty_message: str,
+) -> None:
+    if not isinstance(payload, list):
+        _emit(payload, json_output=False)
+        return
+    rows = [row_builder(item) for item in payload if isinstance(item, dict)]
+    if not rows:
+        print(empty_message)
+        return
+    render_table(headers, rows)
+
+
+def folder_tree_lines(nodes: list[dict[str, Any]], prefix: str = "") -> list[str]:
+    lines: list[str] = []
+    for index, node in enumerate(nodes):
+        is_last = index == len(nodes) - 1
+        marker = "`- " if is_last else "+- "
+        name = str(node.get("name") or "")
+        lines.append(f"{prefix}{marker}{name}  {short_id(node.get('id'))}")
+        child_prefix = f"{prefix}{'   ' if is_last else '|  '}"
+        children = node.get("children")
+        if isinstance(children, list):
+            lines.extend(folder_tree_lines(children, child_prefix))
+    return lines
+
+
+def search_headers() -> list[str]:
+    return ["SCORE", "ITEM", "FILE", "CHUNK", "SOURCE", "TITLE", "SNIPPET"]
+
+
+def search_result_row(item: dict[str, Any]) -> list[str]:
+    return [
+        format_score(item.get("score")),
+        short_id(item.get("item_id")),
+        short_id(item.get("file_id")),
+        str(item.get("chunk_idx") if item.get("chunk_idx") is not None else "-"),
+        str(item.get("source") or "-"),
+        truncate(item.get("title"), 32),
+        truncate(item.get("snippet"), 72),
+    ]
+
+
+def processing_run_row(item: dict[str, Any], *, run_id_field: str) -> list[str]:
+    return [
+        short_id(item.get(run_id_field)),
+        str(item.get("status") or "-"),
+        str(item.get("current_step") or "-"),
+        short_id(item.get("pipeline_id")),
+        truncate(item.get("error_message"), 40),
+    ]
+
+
+def render_table(headers: list[str], rows: list[list[str]]) -> None:
+    widths = [
+        max(len(header), *(len(row[index]) for row in rows))
+        for index, header in enumerate(headers)
+    ]
+    print(
+        "  ".join(header.ljust(widths[index]) for index, header in enumerate(headers))
+    )
+    print("  ".join("-" * width for width in widths))
+    for row in rows:
+        print("  ".join(value.ljust(widths[index]) for index, value in enumerate(row)))
+
+
+def short_id(value: object) -> str:
+    text = str(value or "")
+    return text[:8] if len(text) > 8 else text
+
+
+def bool_mark(value: object) -> str:
+    if value is True:
+        return "yes"
+    if value is False:
+        return "no"
+    return "-"
+
+
+def truncate(value: object, limit: int) -> str:
+    text = " ".join(str(value or "").split())
+    if len(text) <= limit:
+        return text
+    return f"{text[: max(0, limit - 3)]}..."
+
+
+def format_bytes(value: object) -> str:
+    if not isinstance(value, int):
+        return "-"
+    units = ["B", "KB", "MB", "GB"]
+    amount = float(value)
+    for unit in units:
+        if amount < 1024 or unit == units[-1]:
+            if unit == "B":
+                return f"{int(amount)}{unit}"
+            return f"{amount:.1f}{unit}"
+        amount /= 1024
+
+
+def format_score(value: object) -> str:
+    if value is None:
+        return "-"
+    try:
+        return f"{float(value):.3f}"
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def pagination_line(payload: dict[str, Any]) -> str:
+    page = payload.get("page", 1)
+    page_size = payload.get("page_size", len(payload.get("items") or []))
+    total = payload.get("total", len(payload.get("items") or []))
+    return f"page {page}  page_size {page_size}  total {total}"
+
+
+def json_for(command_json: bool) -> bool:
+    return command_json or GLOBAL_JSON
+
+
+def group_to_dict(group: CommandSpec) -> dict[str, object]:
+    return asdict(group)
+
+
+def _emit(payload: Any, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+        return
+
+    if isinstance(payload, list):
+        for item in payload:
+            print(json.dumps(item, ensure_ascii=False, sort_keys=True))
+        return
+    if not isinstance(payload, dict):
+        print(payload)
+        return
+    for key, value in payload.items():
+        if isinstance(value, dict | list):
+            print(f"{key}: {json.dumps(value, ensure_ascii=False, sort_keys=True)}")
+        else:
+            print(f"{key}: {value}")