Find Leads

Finding leads with OpenOutreach

OpenOutreach is a self-hosted CLI lead finder. You describe a product and a target market once; each run discovers candidates from a licensed data source, has an LLM judge each one against that ICP, writes down why, and prints every lead it has as CSV on stdout.

It is one bounded command: ask for an amount, get rows, exit. There is no daemon, no background job, no file the tool writes for the operator, and nothing to poll. If you find yourself wanting to tail a log or wait for something, you have the wrong model of this tool.

It can also send — send mails what is stored, and run is find-then-send in one pass. Both put mail in strangers' inboxes under the user's own identity, so never run either one unless the user asked for mail to go out. find is the default answer to "get me leads"; its deliverable is a CSV for whatever they already send with.

Is it installed?

openoutreach status          # human summary
openoutreach status --json   # the same document, for you to parse

If the command is missing, run it through uvx instead — uvx openoutreach ... — or install it with pip install openoutreach. Inside a checkout of the repo, python manage.py <verb> is the same entry point.

status never blocks and never spends. It answers onboarding (complete or which OPENOUTFIND_* variables are missing), the counts, the credit balance, anything blocked, and a next_action — start there whenever you are unsure what state the user is in. It reports the finding half; the sending half reports itself when send runs.

Setup, if status says onboarding is incomplete

openoutreach init            # interactive wizard on a TTY; environment otherwise

init creates the database, asks for whatever this install has not been told, and stops before spending anything. It is one flow over both halves — the finding first, then what only the sending needs. Every answer can come from the environment instead of a prompt, which is what makes a headless setup possible:

A variable you export is an answer already given, and the wizard skips that question rather than asking for it again. The fields both halves share — what you sell, who for, the model and its key — are asked once and exported under each child's own name (OPENOUTFIND_PRODUCT_DOCS and OUTSEND_PRODUCT_DOCS are the same answer), so there is no second copy to keep in step. On a machine with no TTY, an incomplete install fails naming every variable that would have completed it.

The product description and target market are pages of prose, so pass them as files rather than shell-quoted strings — quoting a markdown paragraph on a command line corrupts it quietly:

openoutreach init --product-docs product.md --target target.md

Never guess the mailbox credentials — ask the user for them.

init is the only verb that asks. find creates the database if it has to, but it never prompts: given an unconfigured install it stops with onboarding_incomplete, naming every variable that would have satisfied it. So run init when the user has not configured anything — it fails cheaply, before any work.

The work verb you reach for

openoutreach find 10                 # ten more qualified leads — free, and cannot spend
openoutreach find 10 --emails        # ...and buy an address for whatever cleared the gate
openoutreach find 10 emails          # ten more *carrying* a verified email (≤10 credits)
openoutreach find 0                  # no work at all — just print what is already there

Three things about N that are easy to get wrong:

• N is how many more, not a total. A store with 30 leads answers find 10 by working until it has 40. Runs are fully resumable; re-running continues rather than restarting.
• find 0 does no work and spends nothing. It is how you re-export, or answer "what do we have?" without running a job.
• N is a budget when the unit is emails. The provider bills one credit per verified hit, so find 10 emails is capped at ten credits by construction — the number typed is in the same unit as the invoice.

What costs money

Discovery and qualification are free (they cost only the user's own LLM key). The address lookup is the only paid step, and it is opt-in:

• a bare find N cannot spend a credit, however many leads are queued past the confidence gate;
• --emails permits buying for whatever is ready;
• the emails unit implies --emails, because a goal counted in addresses cannot be met without buying them.

Do not add emails or --emails unless the user asked for email addresses. If they said "find me leads", run the free form and tell them the paid form exists. A lead with no address still exports — the row carries the person, the company and the reason with a blank email.

Other flags

A run can take a while: each lead is an LLM call, and paid lookups are polled. Give it a generous timeout rather than a short one plus a retry — a killed run wastes the work, though nothing already qualified is lost.

Answering qualify yourself, with no second LLM key

If you (the calling agent) are already reasoning about these leads in this conversation, OPENOUTFIND_LLM_API_KEY is a second, redundant LLM bill for a verdict you can write yourself. Add --agent-qualify and the run stops at the first candidate needing one instead of calling AI_MODEL — and in this mode openoutreach status/find never require a model key at all:

openoutreach find 10 --agent-qualify --json

It runs discovery exactly as normal — free either way — and exits non-zero with qualify_pending, which carries the candidate's own fields right on the error object under --json ({"error": {"type": "qualify_pending", "profile_text", "company", "job_title", "full_name", "profile_url", "lead_id", ...}}, or on the plain-text line without --json). Judge the fit the same way you would judge anything else in this conversation, then re-run the same command with your verdict attached:

openoutreach find 10 --agent-qualify --verdict fit --reason "Series B security infra buyer, matches the ICP on team size and stack."
openoutreach find 10 --agent-qualify --verdict no-fit --reason "Consumer app, not B2B — outside the target market."

This resumes from exactly that candidate — no lead id to track, since at most one is ever pending — records the verdict, and keeps going: either the goal is met, the search runs dry, or it stops again at the next qualify_pending. Nothing already found is lost either way, same as goal_unreached.

--verdict needs both --agent-qualify and --reason — passing one without the other is bad_config. Don't pass --agent-qualify unless you intend to answer every qualify_pending it raises — a bare find without the flag uses AI_MODEL and never stops for a verdict, which is the right default for a run nobody is driving turn-by-turn.

Reading the output

stdout is result-only; logs, counts and progress go to stderr. That is the contract that makes redirection correct:

openoutreach find 10 > leads.csv

stdout carries every lead in the store, not just this run's rows. The newest file supersedes every earlier one, and a lead whose address resolved since last time comes back with it filled in. It is one file to overwrite, never a batch per run — so never append, and never stitch runs together. Rows arrive progressively by default (what is already stored, immediately, then each new lead as it resolves) rather than all at once at the end — the total is the same either way, so this only matters if you are piping into something that cannot take a partial stream, in which case --batch restores the old wait-for-the-end behavior.

Columns, in this order:

email, first_name, last_name, company, title, website, linkedin_url, reason, lead_id, qualified_at

• The names are the importers', not OpenOutreach's: Instantly and Smartlead read email/first_name/last_name and recognise company/title/website/linkedin_url, so the file imports without column mapping. Everything else, reason included, arrives as a custom variable. Do not rename these columns when handing the file on.
• reason is the point — the LLM's written rationale for choosing this person. It is prose, so it contains commas and quotes: parse with a real CSV reader (Python's csv, pandas), never by splitting on ,. When summarising leads for the user, quote the reason; that is what distinguishes these rows from a list bought anywhere else.
• There is no score column, on purpose. The model's confidence is a spend gate for the paid lookup, not a quality signal — do not go looking for one, and do not synthesise one.
• lead_id is the stable key for dedupe across exports. qualified_at is when the verdict landed.
• Rejected leads never export: neither the LLM's "wrong fit" verdict nor a permanent account-level opt-out.
• reason is written for the operator, not the prospect. It justifies a yes/no — third-person and evaluative. Never paste it into a message to the lead.

The CSV is the integration. Instantly, Smartlead, Lemlist, HubSpot, a spreadsheet — the file imports as-is, and there is no adapter, webhook or plugin to look for. One thing to tell the operator when you hand a file on: turn on their tool's import deduplication. It is opt-in on Smartlead and undocumented on Instantly, so a re-exported lead can otherwise be contacted twice.

find 0 is the re-emit path — no work, no spend, prints what is already stored. That is what to run for give me that file again; there is no export verb and none is coming.