autotouch-cli 0.2.81

Autotouch Smart Table CLI

Autotouch CLI

Installable CLI for the Smart Table developer API.

Use it when you want command-driven access to search, tables, columns, runs, jobs, leads, sequences, and task workflows without hand-writing raw HTTP requests.

The CLI talks to the same API the product uses. For automation, prefer --output json.

For a machine-readable local command contract, use autotouch cli-manifest --output json. For a shipped human-readable reference generated from the installed parser, use autotouch cli-reference.

Install

pipx install autotouch-cli
# or
pip install autotouch-cli
# upgrade
pip install -U autotouch-cli

First Run

Existing developer key:

read -s AUTOTOUCH_API_KEY
export AUTOTOUCH_API_KEY
autotouch setup --api-key "$AUTOTOUCH_API_KEY" --base-url https://app.autotouch.ai

Equivalent manual steps:

autotouch auth set-key --api-key "$AUTOTOUCH_API_KEY" --base-url https://app.autotouch.ai
autotouch auth check --base-url https://app.autotouch.ai

Fresh account:

export AUTOTOUCH_CONFIG_PATH=/tmp/autotouch-audit.json
read -s AUTOTOUCH_BOOTSTRAP_PASSWORD
export AUTOTOUCH_BOOTSTRAP_PASSWORD

autotouch auth bootstrap \
  --first-name Ada \
  --last-name Lovelace \
  --email [e-mail] \
  --password "$AUTOTOUCH_BOOTSTRAP_PASSWORD" \
  --organization-name "Audit Org" \
  --save-key

autotouch auth check

Config precedence:

• Explicit flags win over environment variables.
• Environment variables win over saved config.
• Saved config wins over built-in defaults.
• For JSON payload inputs, pass either --data-json or --data-file, not both.

5-Minute Flow

# 0) First-run setup
autotouch setup --api-key "$AUTOTOUCH_API_KEY" --base-url https://app.autotouch.ai

# 1) Inspect machine-readable contract
autotouch capabilities --output json

# 2) Create a table and capture its id
TABLE_ID=$(autotouch tables create --name "CLI Contacts" --output json --select id)

# 3) Add a couple rows with the default lead_finder recipe's expected field
ROW_ID=$(autotouch rows add \
  --table-id "$TABLE_ID" \
  --records-json '[{"domain":"openai.com","companyName":"OpenAI"},{"domain":"stripe.com","companyName":"Stripe"}]' \
  --output json --select rowIds.0)

# 4) Generate a provider-backed column payload
autotouch columns recipe --type lead_finder --out-file column.json

# 5) Create the column and capture its id
COLUMN_ID=$(autotouch columns create --table-id "$TABLE_ID" --data-file column.json --output json --select id)

# 6) Run a small controlled slice and capture the bulk job id
JOB_ID=$(autotouch columns run-next \
  --table-id "$TABLE_ID" \
  --column-id "$COLUMN_ID" \
  --count 2 \
  --show-estimate \
  --wait \
  --output json --select job_id)

# 7) Verify backend truth
autotouch jobs get --job-id "$JOB_ID" --output json

# 8) Inspect exactly what changed
autotouch rows get --table-id "$TABLE_ID" --row-id "$ROW_ID" --output json

Cheat Sheet

• Create table: autotouch tables create
• Add rows: autotouch rows add
• Inspect rows: autotouch rows list, autotouch rows get
• Inspect one cell: autotouch cells get
• Create a workflow column: autotouch columns recipe, autotouch columns create
• Run neural search for niche/specific company or people discovery: autotouch search companies, autotouch search people
• Inspect LinkedIn filters: autotouch linkedin filters --category people
• Build durable company and lead lists on Smart Table workers: autotouch list-build companies, autotouch list-build leads
• Run one LinkedIn search page/debug replay: autotouch linkedin search
• Run controlled slices: autotouch columns run-next
• Poll authoritative state: autotouch jobs get
• Create/activate sequences: autotouch sequences recipe, autotouch sequences create, autotouch sequences activate
• Query leads: autotouch leads query
• Find a lead by email or phone: autotouch leads query --search '<email-or-phone>' --limit 10

Neural Search vs Durable List Build

Autotouch has two different company/people discovery paths.

Use autotouch search companies and autotouch search people for neural search when the target is niche, semantic, or hard to express with structured filters. Examples: "AI workflow platforms for healthcare", "AI workflow startups selling to law firms", or "RevOps operators at PLG SaaS companies". Neural company/people search returns at most 10 results per API call and costs 1 credit per API call.

Use autotouch list-build companies and autotouch list-build leads for structured, repeatable list construction. 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 is the default path for larger LinkedIn-sourced company and lead lists using filters like geography IDs, company size, industry IDs, title/persona, and current company IDs. Durable list builds run as background jobs with status/results endpoints and cost 1 credit per successful non-empty result page.

For structured company builds, start with industry IDs plus geo/company-size filters. Company builds still need a broad keywords anchor (for example, software), but keywords are less reliable because they depend on company/profile text; use them to refine, disambiguate, or recover hard-to-classify targets instead of carrying the whole target definition.

For account-first prospecting, build companies/accounts first, inspect the returned company IDs, then pass those IDs to autotouch list-build leads --current-company-id .... Do not use neural search as a default pre-step for every list build; use it when the user's target is genuinely semantic or niche.

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.81 or newer for the research-workspace list-build guidance, 10-result neural search cap, and provider-hidden autotouch list-build ...; older CLIs may still show the removed autotouch linkedin list-build surface
• 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 list-build companies and autotouch list-build leads for durable provider-hidden company and lead list builds with Smart Table-owned background workers, visible progress, and no user-owned network connection requirement
• autotouch linkedin search for one-page LinkedIn/Sales Navigator replay/debug searches; it is not the recommended path for large lists
• 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

Realtime Table Updates

Research-table cell updates are persistence-first. Writers update Mongo cells; the API-side Mongo change-stream listener emits table-scoped cells_update_batch events. Workers should not emit per-cell socket events directly, and /api/events/emit is not a cell-update transport.

CSV import/export and long-running worker flows still emit low-rate lifecycle/progress events such as table_update, but saved cell state is the source of truth for table rendering. For the full contract, see docs/platform/realtime-events.md and docs/workers/bulk-jobs.md.

LLM Columns

For llm_enrichment in agent mode, the recommended path is:

• provide config.instructions
• let the API compile the runnable prompt
• keep config.useAutoSchema = true

Only send user_schema / response_schema when you intentionally want to override the generated schema and keep it aligned yourself. The installed recipe surface at autotouch columns recipe --type llm_enrichment follows this contract.

Schema ownership rules:

• Accepted generated schemas and explicit user schemas are the saved output contract.
• Row execution must not add fields, rename fields, or replace a valid locked schema.
• Agent-mode evidence/scored state decides which values may fill the schema; the finalizer formats those values and schema validation gates persistence.

Prompt variables in authored prompts support nested JSON access:

• Use flat row variables like {{company_name}} for scalar columns.
• Use dotted placeholders like {{linkedin_lookup.linkedin_url}} when the source column stores JSON or stringified JSON.
• For arrays, use numeric indexes such as {{contacts.0.email}}.
• This is different from config payload mappings, which use objects like { "column": "linkedin_lookup", "path": "linkedin_url" }.

Docs

• Full CLI reference: https://github.com/nicolonic/autotouch_main/blob/main/docs/research-table/reference/autotouch-cli.md
• Agent playbook: https://github.com/nicolonic/autotouch_main/blob/main/docs/research-table/guides/autotouch-cli-agent-playbook.md
• Tables/API reference: https://github.com/nicolonic/autotouch_main/blob/main/docs/research-table/reference/tables-api.md
• Authentication/scopes: https://github.com/nicolonic/autotouch_main/blob/main/docs/platform/authentication.md
• Instantly/Smartlead external sending accounts: https://github.com/nicolonic/autotouch_main/blob/main/docs/integrations/email-automation-platforms.md