autotouch-cli 0.2.25__tar.gz → 0.2.26__tar.gz

{autotouch_cli-0.2.25/autotouch_cli.egg-info → autotouch_cli-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.25
+Version: 0.2.26
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -37,12 +37,13 @@ Use this order when you are orienting in the CLI:
 | verify whether a job is really done | `autotouch jobs get --job-id <JOB_ID>` |
 | create projections from JSON output | `autotouch columns projections` |
 | work with sequences/tasks | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| query/filter CRM leads and attached research | `autotouch leads query` then `autotouch leads research` |
 
 ### Operating model
 
 - This file is the full CLI reference and the package readme published to PyPI.
 - The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
-- Research-table APIs are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
+- Research-table APIs and read-only leads queries are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
 - For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
 - For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
 
@@ -128,6 +129,12 @@ Notes:
 | `POST /api/tables/{table_id}/columns/{column_id}/stop` | `autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>` |
 | `GET /api/bulk-jobs` | `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 10` |
 | `GET /api/bulk-jobs/{job_id}` | `autotouch jobs get --job-id <JOB_ID>` |
+| `POST /api/leads/query` | `autotouch leads query --filter-file lead-filter.json --limit 50` |
+| `POST /api/leads/query/count` | `autotouch leads count --filter-file lead-filter.json` |
+| `POST /api/leads/query/stats` | `autotouch leads stats --filter-file lead-filter.json` |
+| `POST /api/leads/query/research` | `autotouch leads research --lead-id <LEAD_ID> --source-table-id <TABLE_ID>` |
+| `GET /api/leads/filters/metadata` | `autotouch leads filters-metadata` |
+| `GET /api/leads/research-tables/available` | `autotouch leads research-tables` |
 | `GET /api/tables/{table_id}/webhook` | `autotouch webhooks get --table-id <TABLE_ID>` |
 | `POST /api/tables/{table_id}/webhook` | `autotouch webhooks rotate --table-id <TABLE_ID>` |
 | `POST /api/webhooks/tables/{table_id}/ingest` | `autotouch webhooks ingest --table-id <TABLE_ID> --records-file records.json --webhook-token <WEBHOOK_TOKEN>` |
@@ -168,6 +175,61 @@ Signature controls for sequence payloads:
 - `steps[].appendSignature` (optional, step-level) overrides signature behavior for a specific email step.
 - Signature append is deterministic at send time when enabled for the step.
 
+## Leads API coverage
+
+The CLI now exposes the public read-only leads endpoints under `autotouch leads`.
+
+Use this pattern:
+
+1. `autotouch leads query` to page through leads, apply descriptor filters, and inspect `related_tables` / `research_summary`.
+2. `autotouch leads research` when you need actual research field values for specific lead IDs from one source table.
+3. `autotouch leads count` / `autotouch leads stats` when you need sizing before a downstream workflow.
+
+Important contract notes:
+- External callers should use `POST /api/leads/query` rather than the older `GET /api/leads` list route.
+- `autotouch leads query` accepts the same descriptor payload shape as the backend:
+  - `filter`
+  - `search`
+  - `sort`
+  - `pagination`
+  - `scope`
+  - optional research context (`source_table_id`, `source_table_scope`, `related_tables_mode`)
+- Research values are best treated as a follow-up call:
+  - `query` returns lead rows plus research linkage metadata
+  - `research` returns `research_data_by_id` keyed by lead id for one `source_table_id`
+
+Examples:
+
+```bash
+autotouch leads query \
+  --filter-json '{"root":{"kind":"rule","field":"status","operator":"eq","value":"new"}}' \
+  --limit 25
+```
+
+```bash
+autotouch leads count \
+  --search "fintech" \
+  --scope org
+```
+
+```bash
+autotouch leads stats \
+  --source-table-id <TABLE_ID> \
+  --source-table-scope company
+```
+
+```bash
+autotouch leads research \
+  --lead-id <LEAD_ID_1> \
+  --lead-id <LEAD_ID_2> \
+  --source-table-id <TABLE_ID>
+```
+
+```bash
+autotouch leads filters-metadata
+autotouch leads research-tables
+```
+
 ## Bulk job status contract (authoritative run state)
 
 Use bulk jobs as the source of truth for run lifecycle:

autotouch_cli-0.2.25/docs/research-table/reference/autotouch-cli.md → autotouch_cli-0.2.26/autotouch_cli.egg-info/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: autotouch-cli
+Version: 0.2.26
+Summary: Autotouch Smart Table CLI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+
 # Autotouch CLI Reference (`autotouch`)
 
 This page documents the installable CLI for the Smart Table developer API.
@@ -28,12 +37,13 @@ Use this order when you are orienting in the CLI:
 | verify whether a job is really done | `autotouch jobs get --job-id <JOB_ID>` |
 | create projections from JSON output | `autotouch columns projections` |
 | work with sequences/tasks | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| query/filter CRM leads and attached research | `autotouch leads query` then `autotouch leads research` |
 
 ### Operating model
 
 - This file is the full CLI reference and the package readme published to PyPI.
 - The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
-- Research-table APIs are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
+- Research-table APIs and read-only leads queries are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
 - For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
 - For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
 
@@ -119,6 +129,12 @@ Notes:
 | `POST /api/tables/{table_id}/columns/{column_id}/stop` | `autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>` |
 | `GET /api/bulk-jobs` | `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 10` |
 | `GET /api/bulk-jobs/{job_id}` | `autotouch jobs get --job-id <JOB_ID>` |
+| `POST /api/leads/query` | `autotouch leads query --filter-file lead-filter.json --limit 50` |
+| `POST /api/leads/query/count` | `autotouch leads count --filter-file lead-filter.json` |
+| `POST /api/leads/query/stats` | `autotouch leads stats --filter-file lead-filter.json` |
+| `POST /api/leads/query/research` | `autotouch leads research --lead-id <LEAD_ID> --source-table-id <TABLE_ID>` |
+| `GET /api/leads/filters/metadata` | `autotouch leads filters-metadata` |
+| `GET /api/leads/research-tables/available` | `autotouch leads research-tables` |
 | `GET /api/tables/{table_id}/webhook` | `autotouch webhooks get --table-id <TABLE_ID>` |
 | `POST /api/tables/{table_id}/webhook` | `autotouch webhooks rotate --table-id <TABLE_ID>` |
 | `POST /api/webhooks/tables/{table_id}/ingest` | `autotouch webhooks ingest --table-id <TABLE_ID> --records-file records.json --webhook-token <WEBHOOK_TOKEN>` |
@@ -159,6 +175,61 @@ Signature controls for sequence payloads:
 - `steps[].appendSignature` (optional, step-level) overrides signature behavior for a specific email step.
 - Signature append is deterministic at send time when enabled for the step.
 
+## Leads API coverage
+
+The CLI now exposes the public read-only leads endpoints under `autotouch leads`.
+
+Use this pattern:
+
+1. `autotouch leads query` to page through leads, apply descriptor filters, and inspect `related_tables` / `research_summary`.
+2. `autotouch leads research` when you need actual research field values for specific lead IDs from one source table.
+3. `autotouch leads count` / `autotouch leads stats` when you need sizing before a downstream workflow.
+
+Important contract notes:
+- External callers should use `POST /api/leads/query` rather than the older `GET /api/leads` list route.
+- `autotouch leads query` accepts the same descriptor payload shape as the backend:
+  - `filter`
+  - `search`
+  - `sort`
+  - `pagination`
+  - `scope`
+  - optional research context (`source_table_id`, `source_table_scope`, `related_tables_mode`)
+- Research values are best treated as a follow-up call:
+  - `query` returns lead rows plus research linkage metadata
+  - `research` returns `research_data_by_id` keyed by lead id for one `source_table_id`
+
+Examples:
+
+```bash
+autotouch leads query \
+  --filter-json '{"root":{"kind":"rule","field":"status","operator":"eq","value":"new"}}' \
+  --limit 25
+```
+
+```bash
+autotouch leads count \
+  --search "fintech" \
+  --scope org
+```
+
+```bash
+autotouch leads stats \
+  --source-table-id <TABLE_ID> \
+  --source-table-scope company
+```
+
+```bash
+autotouch leads research \
+  --lead-id <LEAD_ID_1> \
+  --lead-id <LEAD_ID_2> \
+  --source-table-id <TABLE_ID>
+```
+
+```bash
+autotouch leads filters-metadata
+autotouch leads research-tables
+```
+
 ## Bulk job status contract (authoritative run state)
 
 Use bulk jobs as the source of truth for run lifecycle:

autotouch_cli-0.2.25/PKG-INFO → autotouch_cli-0.2.26/docs/research-table/reference/autotouch-cli.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: autotouch-cli
-Version: 0.2.25
-Summary: Autotouch Smart Table CLI
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: python-dotenv>=1.0.0
-
 # Autotouch CLI Reference (`autotouch`)
 
 This page documents the installable CLI for the Smart Table developer API.
@@ -37,12 +28,13 @@ Use this order when you are orienting in the CLI:
 | verify whether a job is really done | `autotouch jobs get --job-id <JOB_ID>` |
 | create projections from JSON output | `autotouch columns projections` |
 | work with sequences/tasks | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| query/filter CRM leads and attached research | `autotouch leads query` then `autotouch leads research` |
 
 ### Operating model
 
 - This file is the full CLI reference and the package readme published to PyPI.
 - The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
-- Research-table APIs are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
+- Research-table APIs and read-only leads queries are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
 - For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
 - For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
 
@@ -128,6 +120,12 @@ Notes:
 | `POST /api/tables/{table_id}/columns/{column_id}/stop` | `autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>` |
 | `GET /api/bulk-jobs` | `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 10` |
 | `GET /api/bulk-jobs/{job_id}` | `autotouch jobs get --job-id <JOB_ID>` |
+| `POST /api/leads/query` | `autotouch leads query --filter-file lead-filter.json --limit 50` |
+| `POST /api/leads/query/count` | `autotouch leads count --filter-file lead-filter.json` |
+| `POST /api/leads/query/stats` | `autotouch leads stats --filter-file lead-filter.json` |
+| `POST /api/leads/query/research` | `autotouch leads research --lead-id <LEAD_ID> --source-table-id <TABLE_ID>` |
+| `GET /api/leads/filters/metadata` | `autotouch leads filters-metadata` |
+| `GET /api/leads/research-tables/available` | `autotouch leads research-tables` |
 | `GET /api/tables/{table_id}/webhook` | `autotouch webhooks get --table-id <TABLE_ID>` |
 | `POST /api/tables/{table_id}/webhook` | `autotouch webhooks rotate --table-id <TABLE_ID>` |
 | `POST /api/webhooks/tables/{table_id}/ingest` | `autotouch webhooks ingest --table-id <TABLE_ID> --records-file records.json --webhook-token <WEBHOOK_TOKEN>` |
@@ -168,6 +166,61 @@ Signature controls for sequence payloads:
 - `steps[].appendSignature` (optional, step-level) overrides signature behavior for a specific email step.
 - Signature append is deterministic at send time when enabled for the step.
 
+## Leads API coverage
+
+The CLI now exposes the public read-only leads endpoints under `autotouch leads`.
+
+Use this pattern:
+
+1. `autotouch leads query` to page through leads, apply descriptor filters, and inspect `related_tables` / `research_summary`.
+2. `autotouch leads research` when you need actual research field values for specific lead IDs from one source table.
+3. `autotouch leads count` / `autotouch leads stats` when you need sizing before a downstream workflow.
+
+Important contract notes:
+- External callers should use `POST /api/leads/query` rather than the older `GET /api/leads` list route.
+- `autotouch leads query` accepts the same descriptor payload shape as the backend:
+  - `filter`
+  - `search`
+  - `sort`
+  - `pagination`
+  - `scope`
+  - optional research context (`source_table_id`, `source_table_scope`, `related_tables_mode`)
+- Research values are best treated as a follow-up call:
+  - `query` returns lead rows plus research linkage metadata
+  - `research` returns `research_data_by_id` keyed by lead id for one `source_table_id`
+
+Examples:
+
+```bash
+autotouch leads query \
+  --filter-json '{"root":{"kind":"rule","field":"status","operator":"eq","value":"new"}}' \
+  --limit 25
+```
+
+```bash
+autotouch leads count \
+  --search "fintech" \
+  --scope org
+```
+
+```bash
+autotouch leads stats \
+  --source-table-id <TABLE_ID> \
+  --source-table-scope company
+```
+
+```bash
+autotouch leads research \
+  --lead-id <LEAD_ID_1> \
+  --lead-id <LEAD_ID_2> \
+  --source-table-id <TABLE_ID>
+```
+
+```bash
+autotouch leads filters-metadata
+autotouch leads research-tables
+```
+
 ## Bulk job status contract (authoritative run state)
 
 Use bulk jobs as the source of truth for run lifecycle:

{autotouch_cli-0.2.25 → autotouch_cli-0.2.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.25"
+version = "0.2.26"
 description = "Autotouch Smart Table CLI"
 readme = "docs/research-table/reference/autotouch-cli.md"
 requires-python = ">=3.9"

{autotouch_cli-0.2.25 → autotouch_cli-0.2.26}/scripts/smart_table_cli.py

@@ -998,6 +998,198 @@ def _normalize_run_payload(args: argparse.Namespace) -> Dict[str, Any]:
     return payload
 
 
+def _normalize_filter_payload(filter_payload: Any) -> Any:
+    if filter_payload is None:
+        return None
+    if isinstance(filter_payload, dict):
+        return filter_payload
+    print("ERROR: leads filter payload must be a JSON object", file=sys.stderr)
+    sys.exit(2)
+
+
+def _normalize_sort_payload(sort_payload: Any) -> Any:
+    if sort_payload is None:
+        return None
+    if isinstance(sort_payload, list):
+        return sort_payload
+    if isinstance(sort_payload, dict):
+        return [sort_payload]
+    print("ERROR: leads sort payload must be a JSON object or array", file=sys.stderr)
+    sys.exit(2)
+
+
+def _normalize_leads_query_payload(args: argparse.Namespace) -> Dict[str, Any]:
+    explicit_payload = _load_json_input(
+        inline_json=getattr(args, "data_json", None),
+        file_path=getattr(args, "data_file", None),
+        context="data",
+        default=None,
+    )
+    if explicit_payload is not None:
+        if not isinstance(explicit_payload, dict):
+            print("ERROR: leads payload must be a JSON object", file=sys.stderr)
+            sys.exit(2)
+        return explicit_payload
+
+    payload: Dict[str, Any] = {}
+
+    filter_payload = _normalize_filter_payload(
+        _load_json_input(
+            inline_json=getattr(args, "filter_json", None),
+            file_path=getattr(args, "filter_file", None),
+            context="filter",
+            default=None,
+        )
+    )
+    if filter_payload is not None:
+        payload["filter"] = filter_payload
+
+    sort_payload = _normalize_sort_payload(
+        _load_json_input(
+            inline_json=getattr(args, "sort_json", None),
+            file_path=getattr(args, "sort_file", None),
+            context="sort",
+            default=None,
+        )
+    )
+    if sort_payload is not None:
+        payload["sort"] = sort_payload
+
+    search = str(getattr(args, "search", "") or "").strip()
+    if search:
+        payload["search"] = search
+
+    pagination: Dict[str, Any] = {}
+    limit = getattr(args, "limit", None)
+    if limit is not None:
+        pagination["limit"] = int(limit)
+    cursor = str(getattr(args, "cursor", "") or "").strip()
+    if cursor:
+        pagination["cursor"] = cursor
+    if pagination:
+        payload["pagination"] = pagination
+
+    scope = str(getattr(args, "scope", "") or "").strip()
+    if scope:
+        payload["scope"] = scope
+
+    source_table_id = str(getattr(args, "source_table_id", "") or "").strip()
+    if source_table_id:
+        payload["source_table_id"] = source_table_id
+
+    source_table_scope = str(getattr(args, "source_table_scope", "") or "").strip()
+    if source_table_scope:
+        payload["source_table_scope"] = source_table_scope
+
+    related_tables_mode = str(getattr(args, "related_tables_mode", "") or "").strip()
+    if related_tables_mode:
+        payload["related_tables_mode"] = related_tables_mode
+
+    if bool(getattr(args, "include_research_data", False)):
+        payload["include_research_data"] = True
+
+    if bool(getattr(args, "include_placeholder_leads", False)):
+        payload["include_placeholder_leads"] = True
+
+    return payload
+
+
+def _collect_cli_string_values(raw_values: Optional[List[str]]) -> List[str]:
+    values: List[str] = []
+    for raw in raw_values or []:
+        for piece in str(raw).replace("\n", ",").split(","):
+            normalized = str(piece or "").strip()
+            if normalized:
+                values.append(normalized)
+    return values
+
+
+def _parse_string_list_payload(payload: Any, *, context: str, key: Optional[str] = None) -> List[str]:
+    raw_values: List[Any]
+    if isinstance(payload, list):
+        raw_values = payload
+    elif isinstance(payload, dict) and key and isinstance(payload.get(key), list):
+        raw_values = payload.get(key) or []
+    else:
+        suffix = f" or object with '{key}' array" if key else ""
+        print(f"ERROR: {context} must be a JSON array{suffix}", file=sys.stderr)
+        sys.exit(2)
+
+    values: List[str] = []
+    for item in raw_values:
+        normalized = str(item or "").strip()
+        if normalized:
+            values.append(normalized)
+    return values
+
+
+def _load_string_list_input(
+    *,
+    cli_values: Optional[List[str]],
+    inline_json: Optional[str],
+    file_path: Optional[str],
+    context: str,
+    key: Optional[str] = None,
+) -> List[str]:
+    values = _collect_cli_string_values(cli_values)
+    payload = _load_json_input(
+        inline_json=inline_json,
+        file_path=file_path,
+        context=context,
+        default=None,
+    )
+    if payload is not None:
+        values.extend(_parse_string_list_payload(payload, context=context, key=key))
+    return _dedupe_keep_order(values)
+
+
+def _normalize_leads_research_payload(args: argparse.Namespace) -> Dict[str, Any]:
+    explicit_payload = _load_json_input(
+        inline_json=getattr(args, "data_json", None),
+        file_path=getattr(args, "data_file", None),
+        context="data",
+        default=None,
+    )
+    if explicit_payload is not None:
+        if not isinstance(explicit_payload, dict):
+            print("ERROR: leads research payload must be a JSON object", file=sys.stderr)
+            sys.exit(2)
+        return explicit_payload
+
+    lead_ids = _load_string_list_input(
+        cli_values=getattr(args, "lead_id", None),
+        inline_json=getattr(args, "lead_ids_json", None),
+        file_path=getattr(args, "lead_ids_file", None),
+        context="lead_ids",
+        key="lead_ids",
+    )
+    if not lead_ids:
+        print("ERROR: provide at least one lead id", file=sys.stderr)
+        sys.exit(2)
+
+    source_table_id = str(getattr(args, "source_table_id", "") or "").strip()
+    if not source_table_id:
+        print("ERROR: --source-table-id is required", file=sys.stderr)
+        sys.exit(2)
+
+    payload: Dict[str, Any] = {
+        "lead_ids": lead_ids,
+        "source_table_id": source_table_id,
+    }
+
+    field_ids = _load_string_list_input(
+        cli_values=getattr(args, "field_id", None),
+        inline_json=getattr(args, "field_ids_json", None),
+        file_path=getattr(args, "field_ids_file", None),
+        context="field_ids",
+        key="field_ids",
+    )
+    if field_ids:
+        payload["field_ids"] = field_ids
+
+    return payload
+
+
 def _resolve_column_key(
     *,
     table_id: str,
@@ -3786,6 +3978,98 @@ def cmd_jobs_watch(args: argparse.Namespace) -> None:
         sys.exit(1)
 
 
+def cmd_leads_query(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    payload = _normalize_leads_query_payload(args)
+    data = _request_api(
+        "POST",
+        "/api/leads/query",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_leads_count(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    payload = _normalize_leads_query_payload(args)
+    data = _request_api(
+        "POST",
+        "/api/leads/query/count",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_leads_stats(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    payload = _normalize_leads_query_payload(args)
+    data = _request_api(
+        "POST",
+        "/api/leads/query/stats",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_leads_research(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    payload = _normalize_leads_research_payload(args)
+    data = _request_api(
+        "POST",
+        "/api/leads/query/research",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_leads_filters_metadata(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    data = _request_api(
+        "GET",
+        "/api/leads/filters/metadata",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
+def cmd_leads_research_tables(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    data = _request_api(
+        "GET",
+        "/api/leads/research-tables/available",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    _print_json(data, compact=args.compact)
+
+
 def cmd_webhooks_get(args: argparse.Namespace) -> None:
     token = _resolve_token(args.token, required=True)
     data = _request_api(
@@ -4177,6 +4461,60 @@ def _add_run_execution_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--fail-on-partial", action="store_true", help="Exit non-zero when final status is partial")
 
 
+def _add_leads_query_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--data-json", help="Explicit leads query payload JSON")
+    parser.add_argument("--data-file", help="Path to leads query payload JSON file")
+    parser.add_argument("--filter-json", help="Filter descriptor JSON object")
+    parser.add_argument("--filter-file", help="Path to filter descriptor JSON file")
+    parser.add_argument("--sort-json", help="Sort spec JSON object/array")
+    parser.add_argument("--sort-file", help="Path to sort spec JSON file")
+    parser.add_argument("--search", help="Free-text lead search")
+    parser.add_argument("--limit", type=int, help="Pagination limit")
+    parser.add_argument("--cursor", help="Pagination cursor")
+    parser.add_argument("--scope", choices=["org", "user"], help="Lead scope")
+    parser.add_argument("--source-table-id", help="Research table id used for scope/research context")
+    parser.add_argument(
+        "--source-table-scope",
+        choices=["company", "lead"],
+        help="Research scope resolution mode",
+    )
+    parser.add_argument(
+        "--related-tables-mode",
+        choices=["linked", "direct", "none"],
+        help="How related_tables should be populated",
+    )
+    parser.add_argument(
+        "--include-research-data",
+        action="store_true",
+        help="Inline research_data when --source-table-id is provided",
+    )
+    parser.add_argument(
+        "--include-placeholder-leads",
+        action="store_true",
+        help="Include placeholder/incomplete lead records",
+    )
+
+
+def _add_leads_research_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--data-json", help="Explicit leads research payload JSON")
+    parser.add_argument("--data-file", help="Path to leads research payload JSON file")
+    parser.add_argument(
+        "--lead-id",
+        action="append",
+        help="Lead id (repeatable; comma-separated also supported)",
+    )
+    parser.add_argument("--lead-ids-json", help="JSON array or object with lead_ids[]")
+    parser.add_argument("--lead-ids-file", help="Path to JSON file with lead_ids[]")
+    parser.add_argument("--source-table-id", help="Research table id")
+    parser.add_argument(
+        "--field-id",
+        action="append",
+        help="Research field/column id to include (repeatable; comma-separated also supported)",
+    )
+    parser.add_argument("--field-ids-json", help="JSON array or object with field_ids[]")
+    parser.add_argument("--field-ids-file", help="Path to JSON file with field_ids[]")
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="autotouch", description="Smart Table CLI")
     sub = p.add_subparsers(dest="cmd", required=True)
@@ -4543,6 +4881,38 @@ def build_parser() -> argparse.ArgumentParser:
     pcre.add_argument("--compact", action="store_true", help="Print compact JSON")
     pcre.set_defaults(func=cmd_columns_recipe)
 
+    # leads
+    pl = sub.add_parser("leads", help="Read-only leads query operations")
+    leads_sub = pl.add_subparsers(dest="leads_cmd", required=True)
+
+    plq = leads_sub.add_parser("query", help="Query/filter leads with descriptor payloads")
+    _add_leads_query_arguments(plq)
+    _add_api_common_arguments(plq)
+    plq.set_defaults(func=cmd_leads_query)
+
+    plc = leads_sub.add_parser("count", help="Count leads matching a query payload")
+    _add_leads_query_arguments(plc)
+    _add_api_common_arguments(plc)
+    plc.set_defaults(func=cmd_leads_count)
+
+    pls = leads_sub.add_parser("stats", help="Aggregate stats for leads matching a query payload")
+    _add_leads_query_arguments(pls)
+    _add_api_common_arguments(pls)
+    pls.set_defaults(func=cmd_leads_stats)
+
+    plr = leads_sub.add_parser("research", help="Fetch research row data for specific lead ids")
+    _add_leads_research_arguments(plr)
+    _add_api_common_arguments(plr)
+    plr.set_defaults(func=cmd_leads_research)
+
+    plf = leads_sub.add_parser("filters-metadata", help="List filterable lead fields and research columns")
+    _add_api_common_arguments(plf)
+    plf.set_defaults(func=cmd_leads_filters_metadata)
+
+    plrt = leads_sub.add_parser("research-tables", help="List research tables available for lead lookups")
+    _add_api_common_arguments(plrt)
+    plrt.set_defaults(func=cmd_leads_research_tables)
+
     # jobs
     pj = sub.add_parser("jobs", help="Bulk job operations")
     jobs_sub = pj.add_subparsers(dest="jobs_cmd", required=True)