autotouch-cli 0.2.94__tar.gz → 0.2.98__tar.gz

{autotouch_cli-0.2.94 → autotouch_cli-0.2.98}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.94
+Version: 0.2.98
 Summary: Autotouch Smart Table CLI
 Project-URL: Homepage, https://app.autotouch.ai
 Project-URL: Documentation, https://github.com/nicolonic/autotouch_main/tree/main/docs/research-table/reference
@@ -154,6 +154,16 @@ autotouch rows get --table-id "$TABLE_ID" --row-id "$ROW_ID" --output json
 - Query leads: `autotouch leads query`
 - Find a lead by email or phone: `autotouch leads query --search '<email-or-phone>' --limit 10`
 
+## Sequence Automation Choices
+
+When a user asks to create a campaign sequence, distinguish three separate decisions:
+
+- Manual AI-draft review: `autotouch sequences recipe --type manual_review` (or `create`) sets `executionMode=MANUAL` and `aiDraft=true`; AI drafts content and a human approves/completes each task.
+- Template-based automated send: `autotouch sequences recipe --type automated_template` (or `bulk_automated`) sets `executionMode=AUTOMATED` and `emailSendMode=AUTOMATED` with fixed templates; use this when the user explicitly asks to automate sending without review.
+- LinkedIn-assisted outreach: `autotouch sequences recipe --type linkedin_outreach` uses manual AI-draft LinkedIn connection/message/email fallback tasks after the automated profile visit; use it only when LinkedIn touches are part of the campaign.
+
+If the user says "automate the sequence" without asking for AI-written sends, choose the template-based automated path. Offer manual AI-draft review as the higher-personalization path, but call out that it creates upfront manual tasks while the system learns.
+
 ## Neural Search vs Durable List Build
 
 Autotouch has two different company/people discovery paths.
@@ -166,23 +176,78 @@ Use `autotouch search people` for provider-hidden people search when the target
 
 Use `autotouch list-build companies` and `autotouch list-build leads` for structured, repeatable LinkedIn/Sales Navigator list construction. This is the only CLI path for building LinkedIn-sourced company and lead lists. Treat list builds as the sourcing step for the Smart Table research workspace: build company/account records first by default, add the records to a research table, then enrich, score, segment, find related leads, attach signals/notes, and continue downstream workflows from that table. Use lead builds directly when the request is explicitly person/contact focused. This path uses Autotouch-managed provider access, so users do not need to connect their own LinkedIn account. Use filters like geography IDs, company size, industry IDs, title/persona, and current company IDs; call `autotouch list-build inputs` for supported values. Durable list builds run as background jobs with status/results endpoints and cost 1 credit per successful non-empty result page.
 
+LinkedIn is an optional campaign channel, not the default for every outbound workflow. Use it when the user explicitly wants LinkedIn-sourced lists, profile visits, connection requests, or LinkedIn follow-up tasks. Prefer email/call/custom sequences or research-table workflows when LinkedIn would unnecessarily constrain output because of provider limits, cooldowns, missing profile URLs, or campaign fit.
+
 For structured company builds, start with industry IDs plus geo/company-size filters. User-supplied `keywords` are optional when structured filters are present; use them only to refine, disambiguate, or recover hard-to-classify targets instead of carrying the whole target definition.
 
 For account-first prospecting from LinkedIn/Sales Navigator, build companies/accounts first, inspect the returned company IDs, then pass those IDs to `autotouch list-build leads --current-company-id ...`. Do not use Exa company search as a default pre-step for every LinkedIn list build; use it when the user's target is genuinely semantic, niche, competitor-based, or not meant to be LinkedIn-sourced.
 
 Use `autotouch agents ...` for recurring signal-based discovery. Scheduled agents support `--target ACCOUNTS` for company/account output and `--target LEADS` for people output. Every agent writes a source/signal table for the evidence it used; lead agents then write `candidate_research.candidates[]` on source rows and list-sync those candidates into the lead/candidate output table. See the agent playbook for the full source-table and candidate-sync contract.
 
+## Workflow Plans
+
+Use workflow plans for user goals, and recipes for individual payloads. The clean mental model is:
+
+```text
+discover -> plan -> scaffold -> run primitives -> inspect
+```
+
+- `autotouch integrations list` discovers connected sources and destinations.
+- `autotouch workflows plan --type <TYPE>` explains the recommended path for a goal.
+- `autotouch workflows scaffold --type <TYPE> --out-dir <DIR>` writes payload files and a command runbook.
+- `autotouch columns recipe` and `autotouch sequences recipe` remain leaf-level templates.
+
+Goal-level workflow types include `bulk-outreach`, `company-table-to-people`, `table-to-outreach`, `research-to-sequence`, `account-research`, `signal-outreach`, and `list-build-to-table`. These keep CRM, outreach providers, Autotouch Leads, and Autotouch Sequences as sources/destinations inside one organized workflow layer instead of creating one-off top-level commands.
+
+## Sources And Destinations
+
+Use `autotouch integrations list` before wiring data movement. It returns connected sources and destinations with the directional verbs agents should use:
+
+- `from_crm`: pull HubSpot or Attio records into a research table. Start with `autotouch integrations recipe --type from_crm --provider hubspot`.
+- `to_crm`: push research-table rows to an external CRM such as HubSpot or Attio. Start with `autotouch columns recipe --type to_crm`.
+- `to_outreach`: push research-table rows to an existing Instantly or Smartlead campaign. Start with `autotouch columns recipe --type to_outreach`.
+- `to_leads`: sync research-table rows into Autotouch Leads before sequencing. Start with `autotouch columns recipe --type to_leads`.
+- `to_sequence`: enroll Autotouch Leads into an Autotouch Sequence and assign generated tasks. Start with `autotouch columns recipe --type to_sequence`.
+
+Use the direction in the user's wording. "Pull from HubSpot" means `from_crm`. "Push to HubSpot" means `to_crm`. "Add these leads to this Autotouch sequence" means `to_leads` first when lead IDs do not exist, then `to_sequence`.
+
+CRM round trip:
+
+```bash
+# 1. Confirm the org has the right source/destination connections.
+autotouch integrations list --output json
+autotouch integrations status --provider hubspot
+
+# 2. Pull CRM records into a research table. This prints the API path/body to use;
+# it does not execute the import by itself.
+autotouch integrations recipe --type from_crm --provider hubspot --output json
+
+# 3. Add enrichment columns to the research table.
+autotouch columns recipe --type llm_enrichment --out-file enrich.json
+autotouch columns recipe --type email_finder --out-file email-finder.json
+
+# 4. Push enriched rows back to the CRM, then run the created column.
+autotouch columns recipe --type to_crm --out-file push-to-crm.json
+autotouch columns create --table-id <TABLE_ID> --data-file push-to-crm.json
+autotouch columns run --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope filtered --wait
+```
+
 ## More
 
 For automation or agent-driven setup, use:
 - `autotouch cli-manifest --output json` for the local machine-readable command contract
 - `autotouch cli-reference` for the shipped parser-generated reference
 - `autotouch capabilities --output json` for provider/workflow contracts
-- `autotouch --version` should be `0.2.94` or newer for structured company list builds without user-supplied keywords, stored list-build input lookup, research-workspace list-build guidance, the cleaned single LinkedIn-sourced list-build path, Exa Company Search up to 100 results, scheduled agent `--target ACCOUNTS|LEADS`, paced HTTP Request column contracts, branch-aware LinkedIn sequence recipes, real agent soft-delete with associated-table handling, and research-table sequence handoff assignee config
+- `autotouch --version` should be `0.2.98` or newer for structured company list builds without user-supplied keywords, stored list-build input lookup, research-workspace list-build guidance, the cleaned single LinkedIn-sourced list-build path, Exa Company Search up to 100 results, scheduled agent `--target ACCOUNTS|LEADS`, paced HTTP Request column contracts, branch-aware LinkedIn sequence recipes, real agent soft-delete with associated-table handling, research-table sequence handoff assignee config, backend-owned directional source/destination helpers, and goal-level workflow plans
 - `autotouch capabilities --output json --select list_builds` for documented list-build inputs such as geography IDs, company size buckets, profile language, and company IDs
+- `autotouch integrations list` and `autotouch integrations status --provider <provider>` before choosing source/destination workflows
+- `autotouch workflows plan --type bulk-outreach` and `autotouch workflows scaffold --type bulk-outreach --out-dir workflow` for goal-level workflow planning
+- `autotouch integrations recipe --type from_crm --provider hubspot` for CRM-to-research-table imports
+- `autotouch columns recipe --type to_crm|to_outreach|to_leads|to_sequence` for research-table destination workflows
 - `autotouch list-build inputs` and `autotouch list-build pricing` before creating durable list-build jobs
 - `autotouch list-build companies` and `autotouch list-build leads` for durable LinkedIn-sourced company and lead list builds with Smart Table-owned background workers, visible progress, and no user-owned LinkedIn connection requirement
 - `autotouch linkedin status` and `autotouch linkedin limits` for connected-account diagnostics
+- `autotouch sequences recipe --type linkedin_outreach` only when the campaign should include LinkedIn touches; the emitted branch waits for connection acceptance before LinkedIn chat and uses email fallback after the wait window
 - `autotouch rows list` / `autotouch rows get` / `autotouch cells get` for read-back and audit
 - `autotouch sequences ...` and `autotouch tasks ...` for sequence/task workflows
 - `pip install 'autotouch-cli[mongo]'` if you need the Mongo-backed `status` / `watch` commands

{autotouch_cli-0.2.94 → autotouch_cli-0.2.98}/README.md

@@ -129,6 +129,16 @@ autotouch rows get --table-id "$TABLE_ID" --row-id "$ROW_ID" --output json
 - Query leads: `autotouch leads query`
 - Find a lead by email or phone: `autotouch leads query --search '<email-or-phone>' --limit 10`
 
+## Sequence Automation Choices
+
+When a user asks to create a campaign sequence, distinguish three separate decisions:
+
+- Manual AI-draft review: `autotouch sequences recipe --type manual_review` (or `create`) sets `executionMode=MANUAL` and `aiDraft=true`; AI drafts content and a human approves/completes each task.
+- Template-based automated send: `autotouch sequences recipe --type automated_template` (or `bulk_automated`) sets `executionMode=AUTOMATED` and `emailSendMode=AUTOMATED` with fixed templates; use this when the user explicitly asks to automate sending without review.
+- LinkedIn-assisted outreach: `autotouch sequences recipe --type linkedin_outreach` uses manual AI-draft LinkedIn connection/message/email fallback tasks after the automated profile visit; use it only when LinkedIn touches are part of the campaign.
+
+If the user says "automate the sequence" without asking for AI-written sends, choose the template-based automated path. Offer manual AI-draft review as the higher-personalization path, but call out that it creates upfront manual tasks while the system learns.
+
 ## Neural Search vs Durable List Build
 
 Autotouch has two different company/people discovery paths.
@@ -141,23 +151,78 @@ Use `autotouch search people` for provider-hidden people search when the target
 
 Use `autotouch list-build companies` and `autotouch list-build leads` for structured, repeatable LinkedIn/Sales Navigator list construction. This is the only CLI path for building LinkedIn-sourced company and lead lists. Treat list builds as the sourcing step for the Smart Table research workspace: build company/account records first by default, add the records to a research table, then enrich, score, segment, find related leads, attach signals/notes, and continue downstream workflows from that table. Use lead builds directly when the request is explicitly person/contact focused. This path uses Autotouch-managed provider access, so users do not need to connect their own LinkedIn account. Use filters like geography IDs, company size, industry IDs, title/persona, and current company IDs; call `autotouch list-build inputs` for supported values. Durable list builds run as background jobs with status/results endpoints and cost 1 credit per successful non-empty result page.
 
+LinkedIn is an optional campaign channel, not the default for every outbound workflow. Use it when the user explicitly wants LinkedIn-sourced lists, profile visits, connection requests, or LinkedIn follow-up tasks. Prefer email/call/custom sequences or research-table workflows when LinkedIn would unnecessarily constrain output because of provider limits, cooldowns, missing profile URLs, or campaign fit.
+
 For structured company builds, start with industry IDs plus geo/company-size filters. User-supplied `keywords` are optional when structured filters are present; use them only to refine, disambiguate, or recover hard-to-classify targets instead of carrying the whole target definition.
 
 For account-first prospecting from LinkedIn/Sales Navigator, build companies/accounts first, inspect the returned company IDs, then pass those IDs to `autotouch list-build leads --current-company-id ...`. Do not use Exa company search as a default pre-step for every LinkedIn list build; use it when the user's target is genuinely semantic, niche, competitor-based, or not meant to be LinkedIn-sourced.
 
 Use `autotouch agents ...` for recurring signal-based discovery. Scheduled agents support `--target ACCOUNTS` for company/account output and `--target LEADS` for people output. Every agent writes a source/signal table for the evidence it used; lead agents then write `candidate_research.candidates[]` on source rows and list-sync those candidates into the lead/candidate output table. See the agent playbook for the full source-table and candidate-sync contract.
 
+## Workflow Plans
+
+Use workflow plans for user goals, and recipes for individual payloads. The clean mental model is:
+
+```text
+discover -> plan -> scaffold -> run primitives -> inspect
+```
+
+- `autotouch integrations list` discovers connected sources and destinations.
+- `autotouch workflows plan --type <TYPE>` explains the recommended path for a goal.
+- `autotouch workflows scaffold --type <TYPE> --out-dir <DIR>` writes payload files and a command runbook.
+- `autotouch columns recipe` and `autotouch sequences recipe` remain leaf-level templates.
+
+Goal-level workflow types include `bulk-outreach`, `company-table-to-people`, `table-to-outreach`, `research-to-sequence`, `account-research`, `signal-outreach`, and `list-build-to-table`. These keep CRM, outreach providers, Autotouch Leads, and Autotouch Sequences as sources/destinations inside one organized workflow layer instead of creating one-off top-level commands.
+
+## Sources And Destinations
+
+Use `autotouch integrations list` before wiring data movement. It returns connected sources and destinations with the directional verbs agents should use:
+
+- `from_crm`: pull HubSpot or Attio records into a research table. Start with `autotouch integrations recipe --type from_crm --provider hubspot`.
+- `to_crm`: push research-table rows to an external CRM such as HubSpot or Attio. Start with `autotouch columns recipe --type to_crm`.
+- `to_outreach`: push research-table rows to an existing Instantly or Smartlead campaign. Start with `autotouch columns recipe --type to_outreach`.
+- `to_leads`: sync research-table rows into Autotouch Leads before sequencing. Start with `autotouch columns recipe --type to_leads`.
+- `to_sequence`: enroll Autotouch Leads into an Autotouch Sequence and assign generated tasks. Start with `autotouch columns recipe --type to_sequence`.
+
+Use the direction in the user's wording. "Pull from HubSpot" means `from_crm`. "Push to HubSpot" means `to_crm`. "Add these leads to this Autotouch sequence" means `to_leads` first when lead IDs do not exist, then `to_sequence`.
+
+CRM round trip:
+
+```bash
+# 1. Confirm the org has the right source/destination connections.
+autotouch integrations list --output json
+autotouch integrations status --provider hubspot
+
+# 2. Pull CRM records into a research table. This prints the API path/body to use;
+# it does not execute the import by itself.
+autotouch integrations recipe --type from_crm --provider hubspot --output json
+
+# 3. Add enrichment columns to the research table.
+autotouch columns recipe --type llm_enrichment --out-file enrich.json
+autotouch columns recipe --type email_finder --out-file email-finder.json
+
+# 4. Push enriched rows back to the CRM, then run the created column.
+autotouch columns recipe --type to_crm --out-file push-to-crm.json
+autotouch columns create --table-id <TABLE_ID> --data-file push-to-crm.json
+autotouch columns run --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope filtered --wait
+```
+
 ## More
 
 For automation or agent-driven setup, use:
 - `autotouch cli-manifest --output json` for the local machine-readable command contract
 - `autotouch cli-reference` for the shipped parser-generated reference
 - `autotouch capabilities --output json` for provider/workflow contracts
-- `autotouch --version` should be `0.2.94` or newer for structured company list builds without user-supplied keywords, stored list-build input lookup, research-workspace list-build guidance, the cleaned single LinkedIn-sourced list-build path, Exa Company Search up to 100 results, scheduled agent `--target ACCOUNTS|LEADS`, paced HTTP Request column contracts, branch-aware LinkedIn sequence recipes, real agent soft-delete with associated-table handling, and research-table sequence handoff assignee config
+- `autotouch --version` should be `0.2.98` or newer for structured company list builds without user-supplied keywords, stored list-build input lookup, research-workspace list-build guidance, the cleaned single LinkedIn-sourced list-build path, Exa Company Search up to 100 results, scheduled agent `--target ACCOUNTS|LEADS`, paced HTTP Request column contracts, branch-aware LinkedIn sequence recipes, real agent soft-delete with associated-table handling, research-table sequence handoff assignee config, backend-owned directional source/destination helpers, and goal-level workflow plans
 - `autotouch capabilities --output json --select list_builds` for documented list-build inputs such as geography IDs, company size buckets, profile language, and company IDs
+- `autotouch integrations list` and `autotouch integrations status --provider <provider>` before choosing source/destination workflows
+- `autotouch workflows plan --type bulk-outreach` and `autotouch workflows scaffold --type bulk-outreach --out-dir workflow` for goal-level workflow planning
+- `autotouch integrations recipe --type from_crm --provider hubspot` for CRM-to-research-table imports
+- `autotouch columns recipe --type to_crm|to_outreach|to_leads|to_sequence` for research-table destination workflows
 - `autotouch list-build inputs` and `autotouch list-build pricing` before creating durable list-build jobs
 - `autotouch list-build companies` and `autotouch list-build leads` for durable LinkedIn-sourced company and lead list builds with Smart Table-owned background workers, visible progress, and no user-owned LinkedIn connection requirement
 - `autotouch linkedin status` and `autotouch linkedin limits` for connected-account diagnostics
+- `autotouch sequences recipe --type linkedin_outreach` only when the campaign should include LinkedIn touches; the emitted branch waits for connection acceptance before LinkedIn chat and uses email fallback after the wait window
 - `autotouch rows list` / `autotouch rows get` / `autotouch cells get` for read-back and audit
 - `autotouch sequences ...` and `autotouch tasks ...` for sequence/task workflows
 - `pip install 'autotouch-cli[mongo]'` if you need the Mongo-backed `status` / `watch` commands

{autotouch_cli-0.2.94 → autotouch_cli-0.2.98}/autotouch_cli/cli.py

@@ -75,6 +75,14 @@ from autotouch_cli.commands.jobs import (
     cmd_jobs_list as cmd_jobs_list_impl,
     cmd_jobs_watch as cmd_jobs_watch_impl,
 )
+from autotouch_cli.commands.integrations import (
+    IntegrationCommandRuntime as IntegrationCommandHandlerRuntime,
+    cmd_integrations_from_crm_status as cmd_integrations_from_crm_status_impl,
+    cmd_integrations_list as cmd_integrations_list_impl,
+    cmd_integrations_recipe as cmd_integrations_recipe_impl,
+    cmd_integrations_status as cmd_integrations_status_impl,
+    cmd_integrations_to_crm_status as cmd_integrations_to_crm_status_impl,
+)
 from autotouch_cli.commands.leads import (
     LeadCommandRuntime as LeadCommandHandlerRuntime,
     cmd_leads_count as cmd_leads_count_impl,
@@ -1379,6 +1387,15 @@ def _list_build_command_runtime() -> ListBuildCommandHandlerRuntime:
     )
 
 
+def _integration_command_runtime() -> IntegrationCommandHandlerRuntime:
+    return IntegrationCommandHandlerRuntime(
+        resolve_token=_resolve_token,
+        request_api=_request_api,
+        print_json=lambda data, compact=False: _print_json(data, compact=compact),
+        emit_text=_emit_text,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Command registry — replaces ~110 thin shim functions
 # ---------------------------------------------------------------------------
@@ -1507,6 +1524,13 @@ _register("jobs_get", cmd_jobs_get_impl, _job_command_runtime)
 _register("jobs_list", cmd_jobs_list_impl, _job_command_runtime)
 _register("jobs_watch", cmd_jobs_watch_impl, _job_command_runtime)
 
+# -- Integration commands --
+_register("integrations_list", cmd_integrations_list_impl, _integration_command_runtime)
+_register("integrations_status", cmd_integrations_status_impl, _integration_command_runtime)
+_register("integrations_recipe", cmd_integrations_recipe_impl, _integration_command_runtime)
+_register("integrations_from_crm_status", cmd_integrations_from_crm_status_impl, _integration_command_runtime)
+_register("integrations_to_crm_status", cmd_integrations_to_crm_status_impl, _integration_command_runtime)
+
 # -- Lead commands --
 _register("leads_query", cmd_leads_query_impl, _lead_command_runtime)
 _register("leads_get", cmd_leads_get_impl, _lead_command_runtime)

autotouch_cli-0.2.98/autotouch_cli/commands/integrations.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Sequence
+
+from autotouch_cli.exceptions import AutotouchInputError
+
+
+INTEGRATION_RECIPE_TYPES = ("from_crm",)
+
+_CRM_PROVIDERS = {"hubspot", "attio"}
+_OUTREACH_PROVIDERS = {"instantly", "smartlead"}
+_PROVIDER_LABELS = {
+    "attio": "Attio",
+    "hubspot": "HubSpot",
+    "instantly": "Instantly",
+    "smartlead": "Smartlead",
+}
+
+
+@dataclass(frozen=True)
+class IntegrationCommandRuntime:
+    resolve_token: Callable[[Optional[str], bool], Optional[str]]
+    request_api: Callable[..., Any]
+    print_json: Callable[[Any, bool], None]
+    emit_text: Callable[[str], None]
+
+
+def cmd_integrations_list(args: argparse.Namespace, *, runtime: IntegrationCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET",
+        "/api/integrations/catalog",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    runtime.print_json(data if isinstance(data, dict) else {}, args.compact)
+
+
+def cmd_integrations_status(args: argparse.Namespace, *, runtime: IntegrationCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    provider = str(args.provider or "").strip().lower()
+    if provider not in _CRM_PROVIDERS and provider not in _OUTREACH_PROVIDERS:
+        raise AutotouchInputError("--provider must be one of: hubspot, attio, instantly, smartlead")
+    data = runtime.request_api(
+        "GET",
+        "/api/integrations/catalog",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    integrations = data.get("integrations") if isinstance(data, dict) else []
+    match = next(
+        (item for item in integrations if isinstance(item, dict) and str(item.get("id") or "").lower() == provider),
+        None,
+    )
+    if not match:
+        raise AutotouchInputError(f"provider not present in integration catalog: {provider}")
+    runtime.print_json(match, args.compact)
+
+
+def _from_crm_recipe(provider: str) -> Dict[str, Any]:
+    provider = provider.strip().lower()
+    if provider not in _CRM_PROVIDERS:
+        raise AutotouchInputError("from_crm recipe --provider must be hubspot or attio")
+    return {
+        "provider": provider,
+        "path": f"/api/crm/{provider}/lists/<LIST_ID>/import",
+        "method": "POST",
+        "body": {
+            "table_mode": "create",
+            "table_id": "<TABLE_ID_FOR_APPEND>",
+            "import_type": "company",
+            "selected_fields": ["name", "domain"],
+            "table_name": f"{_PROVIDER_LABELS.get(provider, provider)} Import",
+        },
+        "notes": [
+            "Directional recipe: CRM -> research table.",
+            "Use list_id='filters' with filters[] for filter-based imports.",
+            "Use table_mode='create' for a new research table or 'append' with table_id to add to an existing table.",
+            "Check progress with autotouch integrations from-crm-status --task-id <TASK_ID>.",
+        ],
+    }
+
+
+def cmd_integrations_recipe(args: argparse.Namespace, *, runtime: IntegrationCommandRuntime) -> None:
+    selected_type = str(args.type or "from_crm").strip()
+    if selected_type != "from_crm":
+        raise AutotouchInputError("unsupported integrations recipe type")
+    data = {
+        "type": selected_type,
+        "payload": _from_crm_recipe(str(args.provider or "hubspot")),
+    }
+    runtime.print_json(data, args.compact)
+
+
+def cmd_integrations_from_crm_status(args: argparse.Namespace, *, runtime: IntegrationCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET",
+        f"/api/crm/import-status/{args.task_id}",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def cmd_integrations_to_crm_status(args: argparse.Namespace, *, runtime: IntegrationCommandRuntime) -> None:
+    token = runtime.resolve_token(args.token, required=True)
+    data = runtime.request_api(
+        "GET",
+        f"/api/crm/push-status/{args.task_id}",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    runtime.print_json(data, args.compact)
+
+
+def register_integrations_subcommands(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    *,
+    add_api_common_arguments: Callable[[argparse.ArgumentParser], None],
+    add_output_formatting_arguments: Callable[[argparse.ArgumentParser], None],
+    handlers: Dict[str, Callable[[argparse.Namespace], None]],
+    recipe_types: Sequence[str] = INTEGRATION_RECIPE_TYPES,
+) -> None:
+    parser = subparsers.add_parser(
+        "integrations",
+        help="Discover connected sources/destinations and CRM import/push helpers",
+        description=(
+            "Use this before choosing a workflow. Directional vocabulary: from_crm pulls HubSpot/Attio into "
+            "a research table; to_crm pushes rows to HubSpot/Attio; to_outreach pushes rows to Instantly/Smartlead; "
+            "to_leads syncs rows to Autotouch Leads; to_sequence enrolls Leads into Autotouch Sequences."
+        ),
+    )
+    parser._codex_examples = [
+        "autotouch integrations list",
+        "autotouch integrations status --provider hubspot",
+        "autotouch integrations recipe --type from_crm --provider hubspot",
+        "autotouch columns recipe --type to_crm --out-file push-to-crm.json",
+        "autotouch integrations to-crm-status --task-id <TASK_ID>",
+    ]
+    integrations_sub = parser.add_subparsers(dest="integrations_cmd", required=True)
+
+    plist = integrations_sub.add_parser(
+        "list",
+        help="List available source/destination integrations",
+        description=(
+            "Read the backend-owned integration catalog. The response includes sources, destinations, and recipes. "
+            "Use sources for pull workflows such as from_crm, and destinations for push/sync/enroll workflows such "
+            "as to_crm, to_outreach, to_leads, and to_sequence."
+        ),
+    )
+    plist._codex_examples = [
+        "autotouch integrations list --output json",
+        "autotouch integrations list --select sources",
+        "autotouch integrations list --select destinations",
+    ]
+    add_api_common_arguments(plist)
+    plist.set_defaults(func=handlers["list"])
+
+    pstatus = integrations_sub.add_parser(
+        "status",
+        help="Show connection status for one integration",
+        description=(
+            "Read one provider from the integration catalog. The result shows connected/status/supports so agents can "
+            "decide whether the provider can be used for from_crm, to_crm, or to_outreach before creating workflow columns."
+        ),
+    )
+    pstatus.add_argument("--provider", required=True, choices=["hubspot", "attio", "instantly", "smartlead"])
+    pstatus._codex_examples = [
+        "autotouch integrations status --provider hubspot",
+        "autotouch integrations status --provider instantly --select connected",
+        "autotouch integrations status --provider attio --select supports",
+    ]
+    add_api_common_arguments(pstatus)
+    pstatus.set_defaults(func=handlers["status"])
+
+    precipe = integrations_sub.add_parser(
+        "recipe",
+        help="Print integration workflow payload recipes",
+        description=(
+            "Print payload guidance for integration workflows. This does not execute the workflow; for from_crm, use the "
+            "returned path/body with the API to create or append a research table."
+        ),
+    )
+    precipe.add_argument("--type", choices=list(recipe_types), default="from_crm")
+    precipe.add_argument("--provider", choices=["hubspot", "attio"], default="hubspot")
+    precipe._codex_examples = [
+        "autotouch integrations recipe --type from_crm --provider hubspot",
+        "autotouch integrations recipe --type from_crm --provider attio --output json --compact",
+    ]
+    add_output_formatting_arguments(precipe)
+    precipe.set_defaults(func=handlers["recipe"])
+
+    pfromstatus = integrations_sub.add_parser(
+        "from-crm-status",
+        help="Check a CRM import job",
+        description="Check a CRM import task created by POST /api/crm/{provider}/lists/{list_id}/import.",
+    )
+    pfromstatus.add_argument("--task-id", required=True)
+    pfromstatus._codex_examples = ["autotouch integrations from-crm-status --task-id <TASK_ID>"]
+    add_api_common_arguments(pfromstatus)
+    pfromstatus.set_defaults(func=handlers["from_crm_status"])
+
+    ptostatus = integrations_sub.add_parser(
+        "to-crm-status",
+        help="Check a CRM push job",
+        description="Check a CRM push task created by running a research-table to_crm column.",
+    )
+    ptostatus.add_argument("--task-id", required=True)
+    ptostatus._codex_examples = ["autotouch integrations to-crm-status --task-id <TASK_ID>"]
+    add_api_common_arguments(ptostatus)
+    ptostatus.set_defaults(func=handlers["to_crm_status"])