Lead-Gen-CLI: AI-Powered Lead Scraping and Enrichment from Your Terminal

Every sales team eventually faces the same bottleneck: a list of target companies and nobody to turn into the first ten rows of a pipeline. Lead-Gen-CLI is a small, honest Python command-line tool that automates the unglamorous first stage — fetching candidate leads from public sources, enriching them with company data, scoring their buying intent with a language model, and exporting the result as a CSV ready for a CRM.

The repository (github.com/Shivay00001/Lead-Gen-CLI) is compact: cli.py, a core/ package with four modules, sample inputs, and tests. What makes it worth writing about is not its size but its candor. The README and the code docstrings state, in plain language, exactly which fields are real, which are guessed, and which are placeholders. In a category (lead-gen tooling) famous for fabricated data quality, that honesty is the feature.

The problem it solves

Manual prospecting is slow and repetitive: search a platform for people matching a title and keyword, look up their company, guess an email, score whether they might buy, paste into a spreadsheet. Lead-Gen-CLI collapses that into one command:

python cli.py --keywords "AI SaaS" --title "CTO" --source github --limit 10 --output leads.csv

The pipeline has four stages, each a separate module: fetch (core/fetcher.py) pulls raw prospects from public OSINT — the GitHub API and DuckDuckGo — filtered by keywords, title, and source platform; enrich (core/enricher.py) resolves company domains and constructs candidate emails; intent (core/intent.py) scores buying signals with a language model; export (core/exporter.py) writes the qualified list to CSV. The CLI itself (cli.py) is a typer app with a rich console: spinner statuses per stage, a formatted results table (name, title, company, intent score), and clean logging.

How it works — with the honest limits stated where they belong

Fetch: public OSINT

The fetcher queries public sources — GitHub's API and DuckDuckGo — for people matching the keywords and job title. These are real public data points: names, titles, companies people have published about themselves. The source flag accepts github, linkedin, or twitter. No scraping of gated pages, no credential harvesting; the boundary is public data.

Enrich: real domains, guessed emails

core/enricher.py does two things concurrently (via ThreadPoolExecutor, 5 workers). First, it resolves the company to a real domain using Clearbit's free Autocomplete API (autocomplete.clearbit.com), with a naive heuristic fallback that strips suffixes like inc/llc/ltd and appends .com. Second — and this is where the README earns its credibility — it generates the email as a pattern guess: first.last@domain, or first@domain when only a first name is known. The README states it outright:

Fetched leads come from public OSINT (GitHub API / DuckDuckGo); enrichment emails are guessed patterns (first.last@domain), not verified addresses.

And in the same honest-limits section: company_size is a random placeholder, not real data. Sure enough, the code is random.choice(["10-50", "51-200", "201-500", "500+"]). Most tools would let you discover that in production. This one prints it in the README.

Intent: a real LLM client that refuses to fake scores

core/intent.py is the most interesting module because its docstring is a small essay on data integrity:

"The old g4f (unofficial reverse-engineered client) and Pollinations.ai fallbacks have been removed: they were fragile, unauthenticated, and their 'scores' were fabricated heuristics (score=80 when the word 'score' appeared in the reply)."

The current implementation uses a genuine OpenAI-compatible chat-completions client: OPENAI_API_KEY for auth, configurable OPENAI_BASE_URL (default https://api.openai.com/v1, any OpenAI-compatible endpoint works), configurable OPENAI_MODEL (default gpt-4o-mini), temperature 0, JSON object response format, and a qualify threshold of 60. And the graceful-degradation rule is exactly right: without a valid key, the intent step is skipped — every lead is marked "LLM unavailable" with intent_score: 0 — and the pipeline still completes. No crash, and critically, no fake scores. A lead-gen tool that would rather show zero than invent a number is a tool you can trust with the rest of its output.

Export and tests

The exporter writes the qualified leads to CSV with the fields the pipeline accumulated. The test suite includes tests/test_intent.py and a structural smoke test that AST-parses every Python file to catch syntax breakage. Sample inputs (test_leads.csv, real_leads.csv) ship with the repo so the pipeline can be exercised immediately.

The pipeline's data model

What flows through the four stages is a plain Python dict per lead, growing at each stage — a design that keeps the modules decoupled and the output inspectable:

The dict-passing design means any stage can be swapped: replace the fetcher with a paid data API, the enricher with a verification service, the intent scorer with a local model — the CLI orchestration in cli.py does not care. That separability is what makes the tool genuinely useful as infrastructure rather than a one-off script.

Where it fits in a real outreach workflow

The honest way to use Lead-Gen-CLI is as the top of funnel, not the whole funnel. The pipeline produces candidate rows with real public identity data and best-effort contact guesses; the stages after it — email verification, dedupe against your CRM, personalization, and sending — remain yours. This is the right division of labor: the tool does the mechanical aggregation at machine speed, and humans (or verified services) handle the parts where a wrong guess costs reputation. Used that way, the tool's candor about guessed emails becomes an operational feature: you know exactly which column needs a verification pass before anything is sent.

CLI reference

The dependency footprint is deliberately small — typer, rich, requests, python-dotenv — which means the tool installs in seconds and runs anywhere Python does, including inside larger automation pipelines where a heavy framework would be a liability.

How to run it

Prerequisites: Python 3.8+.

git clone https://github.com/Shivay00001/Lead-Gen-CLI.git
cd Lead-Gen-CLI
pip install -r requirements.txt   # typer, rich, requests, python-dotenv

For intent scoring, set an API key (any OpenAI-compatible endpoint):

export OPENAI_API_KEY="your-key"
# optional:
# export OPENAI_BASE_URL="https://your-compatible-endpoint/v1"
# export OPENAI_MODEL="gpt-4o-mini"

Then run the pipeline:

python cli.py --keywords "AI SaaS" --title "CTO" --source github --limit 10 --output leads.csv

Without the key, the pipeline still runs end to end; intent scores will read 0 with "LLM unavailable" instead of fabricated numbers.

Honest status and roadmap

Status: working CLI, honestly labeled. Fetch, enrich, score, and export all run; the terminal UX (spinners, tables, logging) is genuinely pleasant. The README's own limits section is the accurate status report: emails are pattern guesses, company size is random, and real intent scores require a real key.

The roadmap follows directly: integrate a real email-verification provider (the guessed-pattern emails are the biggest quality gap — verification turns guesses into sendable addresses), replace the random company size with a real firmographic source, add CRM dedupe so re-runs don't re-prospect the same people, and harden the fetcher against source rate limits with backoff and caching. None of these change the architecture; they upgrade the data quality, which is the entire product.

Frequently asked questions

Are the emails verified?

No. They are pattern guesses (first.last@domain) built on a real company domain from Clearbit's autocomplete API. The README states this explicitly. Verify before sending.

What does the AI intent score actually measure?

An LLM (default gpt-4o-mini, temperature 0, JSON output) judges each enriched lead's buying signals against your keywords; leads at or above the threshold of 60 are marked qualified. It requires a real API key.

What happens without an OpenAI API key?

The pipeline completes normally; every lead gets intent_score: 0 labeled "LLM unavailable." Nothing is fabricated.

Which sources can it fetch from?

GitHub and DuckDuckGo-backed public OSINT, via the --source flag (github, linkedin, twitter).

The bottom line

Lead-Gen-CLI does not pretend to be a data vendor. It is a pipeline tool with cleanly separated stages, a genuinely good terminal experience, and documentation that tells you which columns to trust. The old fabricated-score fallbacks were removed on principle, and the code says why. If you need the first draft of a prospect list — real public leads, best-effort enrichment, LLM-scored intent — this is a credible starting point, and the honesty about its limits is why you can believe the parts that work.

That principle generalizes beyond lead generation. Every data pipeline has columns of varying trustworthiness; most tools present them all with equal confidence. Lead-Gen-CLI's approach — label the guesses, zero the scores you cannot compute, keep the pipeline running — is how data tooling should behave everywhere. It is a small repo, but it models a discipline that larger systems routinely fail at.

Source: verified against the public repository github.com/Shivay00001/Lead-Gen-CLI — cli.py, core/fetcher.py, core/enricher.py, core/intent.py, tests, and README read directly.