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 accept the legal notice on the user's behalf. If OPENOUTFIND_ACCEPT_LEGAL_NOTICE is unset, say so and let them set it; do not export it yourself. The same goes for the mailbox credentials: ask, never guess.

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.

The JSON record

For anything programmatic, prefer --json over parsing the CSV. It is JSON Lines: one record per line on stdout, carrying every CSV column plus profile_text — the raw firmographic text the qualifier judged on, which is what a sender writes a message from. The run's own metadata is one JSON object on stderr:

openoutreach find 10 --json > leads.jsonl 2> run.json
openoutreach find 10 --json | jq -r '.email'          # the records

One record, two serialisations: the JSON is the whole thing, the CSV is the importer-safe projection of it. A reader ignores keys it does not know — the finder never renames a key or repurposes one, and only ever adds.

Exit codes and failures

Exit 0 means the goal was met, and nothing else. Anything short still prints its rows and exits non-zero with a single line on stderr:

error: <type>: <message>

Under --json that becomes {"error": {"type": ..., "message": ...}}, still on stderr. The type is a stable string worth branching on:

Treat a non-zero exit as partial success with a stated reason, not as "nothing happened" — the rows are already on stdout. And never report a failed run to the user as "no leads matched": a throttled or unauthorised run that reads as an empty result is the worst possible answer, which is why every failure carries a type.

Handing the leads on

The export is a one-way boundary: leads leave, nothing comes back. There is no inbound endpoint and no callback. Whoever sends owns the conversation, the suppression list and the opt-out duty.

So the natural next step after a run is another tool's importer — Instantly, Smartlead, Lemlist, a CRM, a spreadsheet. Tell the user to switch on their sequencer's import deduplication: it is opt-in on Smartlead and undocumented on Instantly, so a lead exported twice can otherwise be contacted twice.

The verbs that send mail

openoutreach send                    # one pass: open whatever the guards allow right now
openoutreach send 5                  # keep going until five conversations are open
openoutreach run 5                   # find five leads carrying an address, then send

These put real mail in strangers' inboxes, signed with the user's name, from the user's mailbox. Run them only when the user has asked for mail to go out, in this session, in so many words. "Find me some leads" is not that ask, and neither is "set this up".

Three things to know if you do run one:

• run spends. There is no sending without an address, so run N finds in the emails unit — at most N credits — where a bare find N cannot spend at all.
• send has its own clocks. A sending window, a daily cap and pacing between messages all sit between "queued" and "sent", so a pass can legitimately open nothing and still succeed.
• run is find --json piped into the sender, in one process. If the search stops short, what it found is still sent — a partial find is not a failed run.

Everything the sender knows about a lead comes from the finder's JSON record, so the outreach agent's opener is written from profile_text, not from reason.

Writing the opener yourself, with no second LLM key

The sending half has the same opt-out --agent-qualify does, one step later: --agent-draft stops send at the first deal needing an opener instead of spending OUTSEND_LLM_API_KEY, and drops that key out of what send requires entirely:

openoutreach send --agent-draft

It exits non-zero with draft_pending, carrying the deal's profile_text/company/title (on the error object under --json, or the plain-text line without it). Write the opener yourself, then re-run with the answer:

openoutreach send --agent-draft --subject "Quick one" --body "Saw you're hiring for platform roles..."

This resumes the same deal and sends it once a mailbox is free — an answer given while every box is busy is kept, not thrown away, so a later bare openoutreach send --agent-draft picks it back up without repeating the text. No count yet: it is one pass at a time. Still never run this unasked — it is send, and everything in The verbs that send mail above about consent applies unchanged.

Things not to do

• Don't send mail the user didn't ask for. find is the answer to "get me leads"; send and run are answers only to "email them".
• Don't invent a daemon, a scheduler, or a watch loop. Every verb is bounded and exits.
• Don't go looking for an output file. There isn't one unless the user redirected stdout.
• Don't spend credits the user didn't ask for (see What costs money).
• Don't parse stderr for data, or expect data on stdout to be anything but the result.