deepflow-opendesk-cli 0.1.0__py3-none-any.whl

deepflow_opendesk_cli/cli.py

@@ -0,0 +1,696 @@
+"""Command-line interface for OpenDesk admin configuration APIs."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .batch import load_jsonl, run_batch
+from .client import (
+    CliError,
+    HttpResult,
+    OpenDeskClient,
+    host_from_env_or_profile,
+    load_json_payload,
+    parse_key_value,
+    print_json,
+    print_result,
+    token_from_env_or_profile,
+)
+from .profiles import (
+    DEFAULT_PROFILE,
+    delete_profile,
+    load_profile,
+    load_schema_cache,
+    save_profile,
+    save_schema_cache,
+)
+from .schema import (
+    EndpointDoc,
+    build_catalog,
+    fetch_openapi_schema,
+    find_matching_endpoint,
+    get_endpoint,
+    read_schema_file,
+)
+from .workflows import list_workflows, load_workflow_operations
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser."""
+    parser = argparse.ArgumentParser(description="OpenDesk admin configuration API CLI")
+    add_common_args(parser)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    schema = subparsers.add_parser("schema", help="Fetch and inspect OpenAPI schema.")
+    schema_sub = schema.add_subparsers(dest="schema_action", required=True)
+    schema_fetch = schema_sub.add_parser("fetch")
+    schema_fetch.add_argument("--output")
+    schema_export = schema_sub.add_parser("export")
+    schema_export.add_argument("--output")
+    add_schema_arg(schema_export)
+    schema_tags = schema_sub.add_parser("tags")
+    add_schema_arg(schema_tags)
+    schema.set_defaults(handler=handle_schema)
+
+    docs = subparsers.add_parser("docs", help="Query configuration API docs.")
+    docs_sub = docs.add_subparsers(dest="docs_action", required=True)
+    docs_list = docs_sub.add_parser("list")
+    add_schema_arg(docs_list)
+    docs_list.add_argument("--tag")
+    docs_list.add_argument("--method")
+    docs_list.add_argument("--query")
+    docs_show = docs_sub.add_parser("show")
+    add_schema_arg(docs_show)
+    docs_show.add_argument("endpoint")
+    docs_show.add_argument("--json", dest="json_doc", action="store_true")
+    docs.set_defaults(handler=handle_docs)
+
+    request = subparsers.add_parser("request", help="Call a configuration API by method and path.")
+    request.add_argument("method")
+    request.add_argument("path")
+    add_request_args(request)
+    add_schema_arg(request)
+    request.set_defaults(handler=handle_request)
+
+    call = subparsers.add_parser("call", help="Call a configuration API by endpoint key.")
+    call.add_argument("endpoint")
+    call.add_argument("--path", action="append", help="Path parameter as key=value. Repeatable.")
+    add_request_args(call)
+    add_schema_arg(call)
+    call.set_defaults(handler=handle_call)
+
+    auth = subparsers.add_parser("auth", help="Authentication commands.")
+    auth_sub = auth.add_subparsers(dest="auth_action", required=True)
+    login = auth_sub.add_parser("login")
+    login.add_argument("--tenant", required=True)
+    login.add_argument("--username", required=True)
+    login.add_argument("--password")
+    login.add_argument("--save-token", action="store_true")
+    auth_sub.add_parser("me")
+    auth_sub.add_parser("logout")
+    auth.set_defaults(handler=handle_auth)
+
+    add_system_parser(subparsers)
+    add_roles_parser(subparsers)
+    add_employees_parser(subparsers)
+    add_employee_groups_parser(subparsers)
+    add_fields_parser(subparsers)
+    add_forms_parser(subparsers)
+    add_views_parser(subparsers)
+    add_channels_parser(subparsers)
+    add_routing_parser(subparsers)
+    add_queue_parser(subparsers)
+    add_voice_flows_parser(subparsers)
+    add_ticket_workflows_parser(subparsers)
+
+    batch = subparsers.add_parser("batch", help="Run JSONL configuration operations.")
+    batch_sub = batch.add_subparsers(dest="batch_action", required=True)
+    batch_run = batch_sub.add_parser("run")
+    batch_run.add_argument("file")
+    batch_run.add_argument("--continue-on-error", action="store_true")
+    batch_run.add_argument("--output")
+    batch_run.add_argument("--dry-run", action="store_true")
+    batch_run.add_argument("--emit-curl", action="store_true")
+    batch_run.add_argument("--yes", action="store_true")
+    add_schema_arg(batch_run)
+    batch.set_defaults(handler=handle_batch)
+
+    workflow = subparsers.add_parser("workflow", help="Run configuration workflows.")
+    workflow_sub = workflow.add_subparsers(dest="workflow_action", required=True)
+    workflow_sub.add_parser("list")
+    workflow_run = workflow_sub.add_parser("run")
+    workflow_run.add_argument("name")
+    workflow_run.add_argument("--json-file")
+    workflow_run.add_argument("--continue-on-error", action="store_true")
+    workflow_run.add_argument("--dry-run", action="store_true")
+    workflow_run.add_argument("--emit-curl", action="store_true")
+    workflow_run.add_argument("--yes", action="store_true")
+    add_schema_arg(workflow_run)
+    workflow.set_defaults(handler=handle_workflow)
+
+    return parser
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None:
+    """Add global arguments."""
+    parser.add_argument("--host", help="OpenDesk host, for example http://localhost:5001.")
+    parser.add_argument("--base-url", help="API base URL, for example http://localhost:5001/api/v1.")
+    parser.add_argument("--token", help="Bearer token. Defaults to OPENDESK_TOKEN or profile token.")
+    parser.add_argument("--profile", default=DEFAULT_PROFILE, help="Profile name for token and schema cache.")
+    parser.add_argument("--timeout", type=int, default=30)
+    parser.add_argument("--pretty", action=argparse.BooleanOptionalAction, default=True, help="Pretty-print JSON output.")
+    parser.add_argument("--raw", action="store_true", help="Print raw response text for HTTP requests.")
+
+
+def add_schema_arg(parser: argparse.ArgumentParser) -> None:
+    """Add schema-file argument."""
+    parser.add_argument("--schema-file", help="Read OpenAPI schema from a local JSON file.")
+
+
+def add_json_args(parser: argparse.ArgumentParser) -> None:
+    """Add JSON body arguments."""
+    parser.add_argument("--json", help="JSON object payload.")
+    parser.add_argument("--json-file", help="Read JSON object payload from file.")
+
+
+def add_request_args(parser: argparse.ArgumentParser) -> None:
+    """Add common request arguments."""
+    parser.add_argument("--query", action="append", help="Query parameter as key=value. Repeatable.")
+    parser.add_argument("--header", action="append", help="Extra header as key=value. Repeatable.")
+    parser.add_argument("--form-file", action="append", help="Multipart file as field=path. Repeatable.")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--emit-curl", action="store_true")
+    parser.add_argument("--yes", action="store_true", help="Allow destructive requests such as DELETE.")
+    add_json_args(parser)
+
+
+def add_system_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    system = subparsers.add_parser("system", help="System configuration commands.")
+    system_sub = system.add_subparsers(dest="system_action", required=True)
+    system_sub.add_parser("info")
+    settings = system_sub.add_parser("settings")
+    settings_sub = settings.add_subparsers(dest="settings_action", required=False)
+    update = settings_sub.add_parser("update")
+    add_json_args(update)
+    system.set_defaults(handler=handle_system)
+
+
+def add_roles_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    roles = subparsers.add_parser("roles", help="Role configuration commands.")
+    roles_sub = roles.add_subparsers(dest="roles_action", required=True)
+    roles_sub.add_parser("list")
+    roles_sub.add_parser("permission-tree")
+    create = roles_sub.add_parser("create")
+    add_json_args(create)
+    roles.set_defaults(handler=handle_roles)
+
+
+def add_employees_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    employees = subparsers.add_parser("employees", help="Employee configuration commands.")
+    employees_sub = employees.add_subparsers(dest="employees_action", required=True)
+    employees_sub.add_parser("list")
+    create = employees_sub.add_parser("create")
+    add_json_args(create)
+    employees.set_defaults(handler=handle_employees)
+
+
+def add_employee_groups_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    groups = subparsers.add_parser("employee-groups", help="Employee group configuration commands.")
+    groups_sub = groups.add_subparsers(dest="employee_groups_action", required=True)
+    groups_sub.add_parser("list")
+    groups.set_defaults(handler=handle_employee_groups)
+
+
+def add_fields_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    fields = subparsers.add_parser("fields", help="Field definition commands.")
+    fields_sub = fields.add_subparsers(dest="fields_action", required=True)
+    list_cmd = fields_sub.add_parser("list")
+    list_cmd.add_argument("--domain")
+    create = fields_sub.add_parser("create")
+    add_json_args(create)
+    fields.set_defaults(handler=handle_fields)
+
+
+def add_forms_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    forms = subparsers.add_parser("forms", help="Form layout commands.")
+    forms_sub = forms.add_subparsers(dest="forms_action", required=True)
+    by_scene = forms_sub.add_parser("get-by-scene")
+    by_scene.add_argument("scene")
+    forms.set_defaults(handler=handle_forms)
+
+
+def add_views_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    views = subparsers.add_parser("views", help="Workspace view configuration commands.")
+    views_sub = views.add_subparsers(dest="views_action", required=True)
+    list_cmd = views_sub.add_parser("list")
+    list_cmd.add_argument("--resource", required=True, choices=["ticket", "user", "organization"])
+    views.set_defaults(handler=handle_views)
+
+
+def add_channels_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    channels = subparsers.add_parser("channels", help="Channel configuration commands.")
+    channels_sub = channels.add_subparsers(dest="channels_action", required=True)
+    channels_sub.add_parser("list")
+    channels.set_defaults(handler=handle_channels)
+
+
+def add_routing_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    routing = subparsers.add_parser("routing", help="Routing configuration commands.")
+    routing_sub = routing.add_subparsers(dest="routing_scope", required=True)
+    session = routing_sub.add_parser("session")
+    session_sub = session.add_subparsers(dest="routing_action", required=True)
+    session_sub.add_parser("list")
+    inbound = routing_sub.add_parser("inbound")
+    inbound_sub = inbound.add_subparsers(dest="routing_action", required=True)
+    inbound_sub.add_parser("list")
+    routing.set_defaults(handler=handle_routing)
+
+
+def add_queue_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    queue = subparsers.add_parser("queue", help="Queue policy commands.")
+    queue_sub = queue.add_subparsers(dest="queue_action", required=True)
+    queue_sub.add_parser("policies")
+    queue.set_defaults(handler=handle_queue)
+
+
+def add_voice_flows_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    voice = subparsers.add_parser("voice-flows", help="Voice flow configuration commands.")
+    voice_sub = voice.add_subparsers(dest="voice_flows_action", required=True)
+    voice_sub.add_parser("list")
+    voice.set_defaults(handler=handle_voice_flows)
+
+
+def add_ticket_workflows_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    workflows = subparsers.add_parser("ticket-workflows", help="Ticket workflow configuration commands.")
+    workflows_sub = workflows.add_subparsers(dest="ticket_workflows_action", required=True)
+    workflows_sub.add_parser("list")
+    workflows.set_defaults(handler=handle_ticket_workflows)
+
+
+def handle_schema(args: argparse.Namespace) -> int:
+    """Handle schema commands."""
+    if args.schema_action == "fetch":
+        schema = fetch_openapi_schema(resolved_host(args), resolved_token(args), args.timeout)
+        save_schema_cache(args.profile, schema)
+        if args.output:
+            Path(args.output).write_text(json.dumps(schema, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        print_json({"ok": True, "paths": len(schema.get("paths", {}))}, pretty=args.pretty)
+        return 0
+
+    schema = load_schema(args)
+    if args.schema_action == "export":
+        if args.output:
+            Path(args.output).write_text(json.dumps(schema, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+            print_json({"ok": True, "output": args.output}, pretty=args.pretty)
+        else:
+            print_json(schema, pretty=args.pretty)
+        return 0
+
+    catalog = build_catalog(schema)
+    counts: dict[str, int] = {}
+    for endpoint in catalog:
+        counts[endpoint.tag] = counts.get(endpoint.tag, 0) + 1
+    items = [{"tag": tag, "count": count} for tag, count in sorted(counts.items())]
+    print_json(items, pretty=args.pretty)
+    return 0
+
+
+def handle_docs(args: argparse.Namespace) -> int:
+    """Handle docs commands."""
+    catalog = build_catalog(load_schema(args))
+    if args.docs_action == "list":
+        items = [
+            {
+                "key": endpoint.key,
+                "method": endpoint.method,
+                "path": endpoint.path,
+                "tag": endpoint.tag,
+                "summary": endpoint.summary,
+            }
+            for endpoint in filter_catalog(catalog, tag=args.tag, method=args.method, query=args.query)
+        ]
+        print_json(items, pretty=args.pretty)
+        return 0
+
+    endpoint = get_endpoint(catalog, args.endpoint)
+    if args.json_doc:
+        print_json(endpoint.to_dict(), pretty=args.pretty)
+        return 0
+    print_endpoint_text(endpoint)
+    return 0
+
+
+def handle_request(args: argparse.Namespace) -> int:
+    """Handle direct request command."""
+    endpoint = ensure_config_path(args, args.method, args.path)
+    result = execute_request(
+        args,
+        endpoint.method,
+        args.path,
+        query=parse_key_value(args.query),
+        body=optional_payload(args),
+        files=parse_key_value(args.form_file),
+        headers=parse_key_value(args.header),
+        dry_run=args.dry_run,
+        emit_curl=args.emit_curl,
+        yes=args.yes,
+    )
+    return finish_http(args, result)
+
+
+def handle_call(args: argparse.Namespace) -> int:
+    """Handle endpoint-key calls."""
+    catalog = build_catalog(load_schema(args))
+    endpoint = get_endpoint(catalog, args.endpoint)
+    path = fill_path(endpoint.path, parse_key_value(args.path))
+    result = execute_request(
+        args,
+        endpoint.method,
+        path,
+        query=parse_key_value(args.query),
+        body=optional_payload(args),
+        files=parse_key_value(args.form_file),
+        headers=parse_key_value(args.header),
+        dry_run=args.dry_run,
+        emit_curl=args.emit_curl,
+        yes=args.yes,
+    )
+    return finish_http(args, result)
+
+
+def handle_auth(args: argparse.Namespace) -> int:
+    """Handle auth commands."""
+    if args.auth_action == "logout":
+        removed = delete_profile(args.profile)
+        print_json({"ok": True, "removed": removed}, pretty=args.pretty)
+        return 0
+    if args.auth_action == "me":
+        return simple_request(args, "GET", "/api/v1/auth/me")
+
+    password = args.password or getpass.getpass("OpenDesk password: ")
+    body = {"tenant": args.tenant, "username": args.username, "password": password}
+    result = client_from_args(args, token=None).request("POST", "/api/v1/auth/login", body=body)
+    if result.ok and args.save_token and isinstance(result.data, dict):
+        access_token = result.data.get("access_token")
+        if isinstance(access_token, str):
+            save_profile(
+                args.profile,
+                {"host": resolved_host(args), "token": access_token, "user": result.data.get("user")},
+            )
+    return finish_http(args, result)
+
+
+def handle_system(args: argparse.Namespace) -> int:
+    """Handle system commands."""
+    if args.system_action == "info":
+        return simple_request(args, "GET", "/api/v1/system/info")
+    if getattr(args, "settings_action", None) == "update":
+        return simple_request(args, "PUT", "/api/v1/system-settings", body=optional_payload(args))
+    return simple_request(args, "GET", "/api/v1/system-settings")
+
+
+def handle_roles(args: argparse.Namespace) -> int:
+    """Handle role commands."""
+    if args.roles_action == "permission-tree":
+        return simple_request(args, "GET", "/api/v1/roles/permission-tree")
+    if args.roles_action == "create":
+        return simple_request(args, "POST", "/api/v1/roles", body=optional_payload(args))
+    return simple_request(args, "GET", "/api/v1/roles")
+
+
+def handle_employees(args: argparse.Namespace) -> int:
+    """Handle employee commands."""
+    if args.employees_action == "create":
+        return simple_request(args, "POST", "/api/v1/employees", body=optional_payload(args))
+    return simple_request(args, "GET", "/api/v1/employees")
+
+
+def handle_employee_groups(args: argparse.Namespace) -> int:
+    """Handle employee group commands."""
+    return simple_request(args, "GET", "/api/v1/employee-groups")
+
+
+def handle_fields(args: argparse.Namespace) -> int:
+    """Handle field commands."""
+    if args.fields_action == "create":
+        return simple_request(args, "POST", "/api/v1/field-definitions", body=optional_payload(args))
+    query = {"domain": args.domain} if args.domain else None
+    return simple_request(args, "GET", "/api/v1/field-definitions", query=query)
+
+
+def handle_forms(args: argparse.Namespace) -> int:
+    """Handle form commands."""
+    return simple_request(args, "GET", f"/api/v1/form-layouts/by-scene/{args.scene}")
+
+
+def handle_views(args: argparse.Namespace) -> int:
+    """Handle view commands."""
+    path_by_resource = {
+        "ticket": "/api/v1/ticket-views",
+        "user": "/api/v1/user-views",
+        "organization": "/api/v1/organization-views",
+    }
+    return simple_request(args, "GET", path_by_resource[args.resource])
+
+
+def handle_channels(args: argparse.Namespace) -> int:
+    """Handle channel commands."""
+    return simple_request(args, "GET", "/api/v1/channels")
+
+
+def handle_routing(args: argparse.Namespace) -> int:
+    """Handle routing commands."""
+    if args.routing_scope == "inbound":
+        return simple_request(args, "GET", "/api/v1/inbound-routing-rules")
+    return simple_request(args, "GET", "/api/v1/session-routing-rules")
+
+
+def handle_queue(args: argparse.Namespace) -> int:
+    """Handle queue commands."""
+    return simple_request(args, "GET", "/api/v1/queue/policies")
+
+
+def handle_voice_flows(args: argparse.Namespace) -> int:
+    """Handle voice-flow commands."""
+    return simple_request(args, "GET", "/api/v1/voice-flows")
+
+
+def handle_ticket_workflows(args: argparse.Namespace) -> int:
+    """Handle ticket-workflow commands."""
+    return simple_request(args, "GET", "/api/v1/ticket-workflows")
+
+
+def handle_batch(args: argparse.Namespace) -> int:
+    """Handle batch commands."""
+    operations = load_jsonl(args.file)
+    results = run_batch(
+        operations,
+        lambda operation: run_operation(args, operation, dry_run=args.dry_run, emit_curl=args.emit_curl, yes=args.yes),
+        continue_on_error=args.continue_on_error,
+    )
+    text = "\n".join(json.dumps(item, ensure_ascii=False) for item in results) + "\n"
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+    print(text, end="")
+    return 0 if all(item.get("ok") for item in results) else 1
+
+
+def handle_workflow(args: argparse.Namespace) -> int:
+    """Handle workflow commands."""
+    if args.workflow_action == "list":
+        print_json(list_workflows(), pretty=args.pretty)
+        return 0
+    operations = load_workflow_operations(args.name, args.json_file)
+    results = run_batch(
+        operations,
+        lambda operation: run_operation(args, operation, dry_run=args.dry_run, emit_curl=args.emit_curl, yes=args.yes),
+        continue_on_error=args.continue_on_error,
+    )
+    print("\n".join(json.dumps(item, ensure_ascii=False) for item in results))
+    return 0 if all(item.get("ok") for item in results) else 1
+
+
+def simple_request(
+    args: argparse.Namespace,
+    method: str,
+    path: str,
+    *,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+) -> int:
+    """Run a known-safe configuration request."""
+    result = execute_request(args, method, path, query=query, body=body)
+    return finish_http(args, result)
+
+
+def execute_request(
+    args: argparse.Namespace,
+    method: str,
+    path: str,
+    *,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+    files: dict[str, str] | None = None,
+    headers: dict[str, str] | None = None,
+    dry_run: bool = False,
+    emit_curl: bool = False,
+    yes: bool = False,
+) -> HttpResult:
+    """Execute a request with destructive-operation protection."""
+    if method.upper() == "DELETE" and not (yes or dry_run):
+        raise CliError("DELETE requires --yes or --dry-run")
+    return client_from_args(args).request(
+        method,
+        path,
+        query=query,
+        body=body,
+        files=files,
+        headers=headers,
+        dry_run=dry_run,
+        emit_curl=emit_curl,
+    )
+
+
+def run_operation(
+    args: argparse.Namespace,
+    operation: dict[str, Any],
+    *,
+    dry_run: bool,
+    emit_curl: bool,
+    yes: bool,
+) -> HttpResult:
+    """Run a batch/workflow operation."""
+    if "key" in operation:
+        catalog = build_catalog(load_schema(args))
+        endpoint = get_endpoint(catalog, str(operation["key"]))
+        path = fill_path(endpoint.path, operation.get("path") or {})
+        method = endpoint.method
+    else:
+        method = str(operation.get("method") or "").upper()
+        path = str(operation.get("path") or "")
+        if not method or not path:
+            raise CliError("Batch operation requires either key or method/path")
+        ensure_config_path(args, method, path)
+    return execute_request(
+        args,
+        method,
+        path,
+        query=operation.get("query") if isinstance(operation.get("query"), dict) else None,
+        body=operation.get("body") if isinstance(operation.get("body"), dict) else None,
+        files=operation.get("files") if isinstance(operation.get("files"), dict) else None,
+        dry_run=dry_run,
+        emit_curl=emit_curl,
+        yes=yes,
+    )
+
+
+def ensure_config_path(args: argparse.Namespace, method: str, path: str) -> EndpointDoc:
+    """Ensure a concrete path is in the configuration API catalog."""
+    catalog = build_catalog(load_schema(args))
+    endpoint = find_matching_endpoint(catalog, method, path)
+    if endpoint is None:
+        raise CliError(f"{method.upper()} {path} is not in the admin configuration API catalog")
+    return endpoint
+
+
+def fill_path(template: str, params: dict[str, Any]) -> str:
+    """Fill a path template with path parameters."""
+    path = template
+    for name in [part[1:-1] for part in template.split("/") if part.startswith("{") and part.endswith("}")]:
+        if name not in params:
+            raise CliError(f"Missing path parameter: {name}")
+        path = path.replace("{" + name + "}", str(params[name]))
+    return path
+
+
+def filter_catalog(
+    catalog: list[EndpointDoc],
+    *,
+    tag: str | None = None,
+    method: str | None = None,
+    query: str | None = None,
+) -> list[EndpointDoc]:
+    """Filter catalog rows for docs list."""
+    result = catalog
+    if tag:
+        result = [item for item in result if item.tag == tag]
+    if method:
+        result = [item for item in result if item.method == method.upper()]
+    if query:
+        needle = query.lower()
+        result = [
+            item
+            for item in result
+            if needle in item.key.lower()
+            or needle in item.path.lower()
+            or needle in item.summary.lower()
+        ]
+    return result
+
+
+def print_endpoint_text(endpoint: EndpointDoc) -> None:
+    """Print a human-readable endpoint document."""
+    print(endpoint.key)
+    print(f"  {endpoint.method} {endpoint.path}")
+    print(f"  tag: {endpoint.tag}")
+    print(f"  operation_id: {endpoint.operation_id}")
+    print(f"  auth: {'required' if endpoint.requires_auth else 'not required'}")
+    print(f"  summary: {endpoint.summary}")
+    if endpoint.path_params:
+        print("  path params:")
+        for item in endpoint.path_params:
+            print(f"    - {item.name} ({item.type}, required={item.required}): {item.description}")
+    if endpoint.query_params:
+        print("  query params:")
+        for item in endpoint.query_params:
+            print(f"    - {item.name} ({item.type}, required={item.required}): {item.description}")
+    if endpoint.body_schema:
+        print(f"  body_schema: {endpoint.body_schema}")
+    if endpoint.response_schema:
+        print(f"  response_schema: {endpoint.response_schema}")
+    for example in endpoint.examples:
+        print(f"  example: {example}")
+
+
+def optional_payload(args: argparse.Namespace) -> dict[str, Any] | None:
+    """Return JSON payload or None when no payload was provided."""
+    payload = load_json_payload(getattr(args, "json", None), getattr(args, "json_file", None))
+    return payload if payload else None
+
+
+def client_from_args(args: argparse.Namespace, token: str | None | object = ... ) -> OpenDeskClient:
+    """Create an HTTP client from CLI args."""
+    profile_data = load_profile(args.profile)
+    resolved = resolved_token(args, profile_data) if token is ... else token
+    return OpenDeskClient(host=resolved_host(args, profile_data), token=resolved, timeout=args.timeout)
+
+
+def resolved_host(args: argparse.Namespace, profile_data: dict[str, Any] | None = None) -> str:
+    """Resolve host from args, environment, or profile."""
+    profile_data = profile_data if profile_data is not None else load_profile(args.profile)
+    return host_from_env_or_profile(host=args.host, base_url=args.base_url, profile_data=profile_data)
+
+
+def resolved_token(args: argparse.Namespace, profile_data: dict[str, Any] | None = None) -> str | None:
+    """Resolve token from args, environment, or profile."""
+    profile_data = profile_data if profile_data is not None else load_profile(args.profile)
+    return token_from_env_or_profile(token=args.token, profile_data=profile_data)
+
+
+def load_schema(args: argparse.Namespace) -> dict[str, Any]:
+    """Load schema from file, cache, or remote host."""
+    schema_file = getattr(args, "schema_file", None)
+    if schema_file:
+        return read_schema_file(schema_file)
+    cached = load_schema_cache(args.profile)
+    if cached:
+        return cached
+    schema = fetch_openapi_schema(resolved_host(args), resolved_token(args), args.timeout)
+    save_schema_cache(args.profile, schema)
+    return schema
+
+
+def finish_http(args: argparse.Namespace, result: HttpResult) -> int:
+    """Print an HTTP result and return a process code."""
+    print_result(result, pretty=args.pretty, raw=args.raw)
+    return 0 if result.ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.handler(args)
+    except (CliError, KeyError, RuntimeError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())