Lessie CLI

People search, enrichment & web research from the command line.

Search 275M+ professionals, enrich contacts, discover companies, and research the web — all powered by the Lessie platform.

Install

npm install -g @lessie/cli

Or run without installing:

npx @lessie/cli --help

Quick Start

# Authorize (opens browser for OAuth)
lessie auth

# Search people (natural-language task, passed verbatim)
lessie find-people --query "CTOs at US tech companies" --target-count 20

# Enrich a person by LinkedIn URL
lessie enrich-people \
  --people '[{"linkedin_url":"https://linkedin.com/in/samaltman"}]'

# Enrich a company by domain
lessie enrich-org --domains stripe.com

# Search the web
lessie web-search --query 'AI startups 2026'

Cost-aware usage

Lessie is credit-based. The biggest source of wasted credits is calling the wrong tool before find-people — pre-searching with web-search, or "verifying" a domain with enrich-org before a people search. The table below shows the real cost of each command; the rules and anti-patterns that follow are how to keep the bill close to the floor.

Per-command cost

| Command | Cost | Notes | |---|---|---| | find-people | 20 credits / call, flat | Charged once if any result is found; zero on empty result. Up to 100 people per call — one large call beats many small ones. | | enrich-people | 1 credit / person successfully enriched | Zero on not-found. Max 10 per call. | | enrich-org | 1 credit / call | Max 10 domains per call. | | find-orgs | 1 credit / call | Independent of result count. | | web-search | 1 credit / call | Independent of --count. | | web-fetch | 0 credits | Reads the cache populated by web-search. | | unlock-emails / unlock-email-by-handle | Per successful unlock | Already-unlocked people in any prior search are free (idempotent for search-scoped form). | | unlock-phones / unlock-phone-by-handle | Per successful unlock | Same cost model as email unlocks. | | review-people, tools, call, auth, status | 0 credits (tooling) | |

Efficiency rules

1. One big find-people beats many small ones. Billing is per call, not per result. Splitting "find 100 engineers" into 5 × 20-count calls costs 100 credits instead of 20 for the same answer. Always set --target-count to the full number the user asked for (up to the 100 single-call cap).
2. Pack every constraint into the --query string. Company, title, seniority, location, niche, audience size, exclusions — all of it. find-people resolves domains, expands niche keywords, and disambiguates entities internally. You don't need to pre-research.
3. Skip the pre-search. Don't run web-search, find-orgs, or enrich-org "to look up the domain / company" before find-people. Every pre-search adds credits to a flow that find-people already handles end-to-end for 20 credits flat.
4. Only enrich-people when the user asks for the extra fields. The profile fields find-people already returns (title, headline, linkedin_url, organization, etc.) are usually enough. Only call enrich-people when the user explicitly needs email, phone, employment history, or full work bio. Don't auto-enrich every result.
5. Use web-fetch for cached pages. When web-search returns has_content: true, the full page text is in the cache — web-fetch reads it for 0 credits instead of paying for another web-search.

Anti-patterns (don't do this)

• ❌ web-search "OpenAI official website" → enrich-org --domains openai.com → find-people --query "engineers at OpenAI" ✅ Just find-people --query "engineers at OpenAI" — it resolves the entity itself.
• ❌ Five find-people --target-count 20 calls in a row to collect 100 people (= 100 credits) ✅ One find-people --target-count 100 (= 20 credits).
• ❌ enrich-people on every result from a find-people search "just in case" ✅ Only enrich the rows the user explicitly wants extended fields for.
• ❌ find-orgs as a pre-step before find-people ✅ find-orgs is for discovering companies as the goal (lead lists, market mapping), not as scaffolding for a people search.

Commands

Meta

| Command | Cost | Description | |---|---|---| | auth | — | Authorize with Lessie (opens browser) | | status | — | Show connection & token status | | tools | — | List all available remote tools | | call <tool> | varies by tool | Call any remote tool by name |

People

| Command | Cost | Description | |---|---|---| | find-people | 20 / call (up to 100 results) | Natural-language people search from 275M+ database | | search-people | 3 / 25 results (empty = free) | Structured people search — exact filters (title, seniority, location, company size/domain/revenue, hiring signals, email status) | | enrich-people | 1 / person | Enrich known people with full profiles | | review-people | — | Deep-review people from a previous search | | unlock-emails | per unlock | Unlock emails for people from a prior find-people search (idempotent, search-scoped) | | unlock-email-by-handle | per unlock | Unlock emails by social handle without a prior search (not idempotent) | | unlock-phones | per unlock | Unlock company phones for people from a prior find-people search (idempotent, search-scoped) | | unlock-phone-by-handle | per unlock | Unlock phones by LinkedIn handle without a prior search (LinkedIn only) |

Organizations

| Command | Cost | Description | |---|---|---| | find-orgs | 1 / call | Discover companies by criteria | | enrich-org | 1 / call | Enrich organizations by domain | | job-postings | per provider | Get active job openings for a company | | company-news | per provider | Search news articles for companies |

Web

| Command | Cost | Description | |---|---|---| | web-search | 1 / call | Search the open web | | web-fetch | 0 | Fetch & extract info from a URL (reads web-search cache) |

Run lessie help <command> for detailed usage of any command.

Global Options

--env <name>      Environment: prod (default), staging/s6/test
--url <url>       Custom remote MCP server URL (overrides --env;
                  must appear BEFORE the command name)
--timeout <secs>  Request timeout in seconds (default: 300)
--pretty          Pretty-print JSON output
--help, -h        Show help
--version, -v     Show version

--env, --timeout and --pretty are recognized anywhere on the command line (lessie status --env staging works). --url is only global before the command name because web-fetch has its own --url flag.

Unknown flags are an error, not silently ignored — a typo like --target-cuont fails immediately with the list of valid flags.

Environment Variables

| Variable | Description | |---|---| | LESSIE_REMOTE_MCP_URL | Remote server URL (overrides --env) |

Examples

Find senior engineers at AI companies

lessie find-people \
  --query "Senior ML engineers at AI companies in the US" \
  --target-count 20

Pass the user's request verbatim — the agent picks sources and keywords itself, and niche terms ("fintech", "web3") matter for search quality. Don't pre-search with web-search or enrich-org first — every extra call adds credits to a flow find-people already handles.

Find 100 results in one call (not five)

lessie find-people \
  --query "Senior ML engineers at AI companies in the US" \
  --target-count 100

20 credits for 100 people. Splitting this into 5 × --target-count 20 calls costs 100 credits for the same answer.

Find KOL / influencer

lessie find-people \
  --query "Instagram beauty creators with 100k+ followers in the US"

Enrich multiple companies

lessie enrich-org --domains '["stripe.com","openai.com"]'

Review candidates from a search

lessie review-people \
  --search-id 'mcp_abc123' \
  --person-ids '["id1","id2"]' \
  --checkpoints '[{"key":"relevance","title":"Relevance","description":"Is this person a senior ML engineer?","category":"career"}]'

Unlock emails from a prior search

lessie unlock-emails \
  --search-id 'mcp_abc123' \
  --person-ids '["65a1f3c2d4e5f6a7b8c9d0e1","65a1f3c2d4e5f6a7b8c9d0e2"]'

Already-unlocked people are returned at zero cost; new unlocks are charged at the per-email rate. Cross-search dedup applies (the same person unlocked in any prior search is free).

Unlock emails by social handle (no prior search)

lessie unlock-email-by-handle \
  --handles '[{"platform":"linkedin","handle":"samaltman"},{"platform":"twitter","handle":"elonmusk"}]'

Use this when you already have a known handle and want to skip find-people. Charged per successful unlock; failures are free. Not idempotent — re-querying the same handle charges again.

Unlock phones from a prior search

lessie unlock-phones \
  --search-id 'mcp_abc123' \
  --person-ids '["65a1f3c2d4e5f6a7b8c9d0e1"]'

Same cost model as unlock-emails: already-unlocked people are free, cross-search dedup applies.

Unlock phones by LinkedIn handle (no prior search)

lessie unlock-phone-by-handle \
  --handles '[{"platform":"linkedin","handle":"samaltman"}]'

LinkedIn handles only — other platforms return unsupported_platform.

Discover companies by criteria

lessie find-orgs \
  --keyword-tags '["AI","SaaS"]' \
  --locations '["United States"]' \
  --employees '["51,200"]'

Authentication

Lessie CLI uses OAuth for authentication. Run lessie auth to authorize — it opens your browser for login and stores tokens locally at ~/.lessie/<server-host>/oauth.json (one token set per environment).

Tokens refresh automatically. Run lessie status to check your current auth state.

License

MIT