salesprompter-cli 0.1.20 → 0.1.23

package/README.md

@@ -1,338 +1,64 @@
 # salesprompter-cli
 
-`salesprompter-cli` is a JSON-first command line interface for running a practical sales workflow:
+Salesprompter CLI helps you go from company or product input to qualified leads with a guided terminal flow.
 
-- Authenticate via Salesprompter app backend
-- Crawl LinkedIn product categories
-- Derive intended-role job titles
-- Split broad Sales Navigator searches into exportable slices
-- Export those slices through Phantombuster
-- Store product and people data in Salesprompter
-- Enrich leads
-- Score leads
-- Sync leads into CRM and outreach systems
-- Analyze upstream lead-list and domain-enrichment bottlenecks
-- Replace opaque Pipedream logic with deterministic CLI workflows
-
-It is built for two users at the same time:
-
-- humans working in a terminal
-- coding agents such as Codex, Claude Code, and other LLM-driven shell workflows
-
-The app, CLI, and Chrome extension all write into one shared Salesprompter backend and database. Access is scoped to
-the active workspace you choose at login.
-
-## Start Here
-
-If someone discovers Salesprompter from a vague prompt, give them the shortest working path for their context.
+## Install
 
 ```bash
-## Human-friendly guided path
-npx -y salesprompter-cli@latest
-
-## Explicit guided path
-npx -y salesprompter-cli@latest wizard
-
-## Primary raw command for agents and scripts
-npx -y salesprompter-cli@latest salesnav:from-product-category --input deel.com --dry-run
+npm i -g salesprompter-cli
 ```
 
-Or install it globally:
-
-```bash
-npm install -g salesprompter-cli
-salesprompter
-salesprompter wizard
-salesprompter --help
-```
-
-Bare `salesprompter` now opens a guided wizard in an interactive terminal. Keep using explicit subcommands for agents, CI, and copy-paste docs.
-If your Salesprompter user belongs to multiple workspaces, browser login asks which workspace the CLI session should use.
-
-## Prompt To Command
-
-The primary live path is:
-
-1. crawl a LinkedIn product category
-2. derive the intended job titles
-3. turn those into Sales Navigator queries
-4. split broad searches into exportable chunks
-5. export them through Phantombuster
-6. store everything in Salesprompter
-
-### "I sell for Deel and want the right people at similar companies"
-
-Start from the company, product, or category input:
-
-```bash
-salesprompter salesnav:from-product-category --input deel.com
-```
-
-The CLI now stays attached while durable title crawls are still running remotely, writes JSONL trace logs, and exits non-zero if any title crawl finishes with failures. Use `--allow-partial-success` only when you explicitly want a best-effort run.
-
-Preview the generated titles and first split queries before creating crawl jobs:
-
-```bash
-salesprompter --json salesnav:from-product-category --input deel.com --dry-run
-```
-
-### "Find people at deel.com"
-
-That is still a direct target-company lookup:
-
-```bash
-salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
-```
-
-### Historical warehouse fallback
-
-`salesnav:ensure-count` remains a historical backfill path, not the primary workflow:
-
-```bash
-salesprompter salesnav:ensure-count --target-count 200000 --org-id "$SALESPROMPTER_ORG_ID"
-```
-
-## Documentation
-
-This repository now includes the public Salesprompter docs site for the wider Salesprompter universe, including the app contract, CLI surface, Chrome extension contract, and the main warehouse-backed workflows.
-
-- Live docs: `https://salesprompter-cli.vercel.app`
-
-- Docs home: `./index.mdx`
-- Quickstart: `./quickstart.mdx`
-- Architecture: `./architecture.mdx`
-- App: `./platform/app.mdx`
-- CLI: `./platform/cli.mdx`
-- Chrome extension: `./platform/chrome-extension.mdx`
-- Domain finder: `./workflows/domain-finder.mdx`
-- Command reference: `./reference/cli.mdx`
-- Environment variables: `./reference/environment-variables.mdx`
-- Troubleshooting: `./operations/troubleshooting.mdx`
-
-Run the docs locally with:
+or run directly:
 
 ```bash
-npm run docs:dev
+npx -y salesprompter-cli@latest
 ```
 
-Build the deployable static docs site with:
+## Quickstart
 
 ```bash
-npm run build:docs:site
-```
-
-## Integration Contract
-
-This CLI is not a standalone toy. It is a production integration surface for the Salesprompter app.
-
-- The Domain Finder flow in this repository is a real end-to-end test case for Salesprompter app integration.
-- CLI behavior should be treated as an app contract: auth, BigQuery execution, artifacts, and writeback semantics must remain stable.
-- Changes to domain selection, writeback, or audit logic should always be validated with:
-  - CLI tests (`npm test`)
-  - BigQuery-backed runs (`domainfinder:run:bq`, `domainfinder:audit-existing:bq`)
-  - before/after delta checks (`domainfinder:audit-delta`)
-
-The current live path is product-first. It resolves a LinkedIn product category, derives intended-role Sales Navigator searches, and lets the app run durable exports through Phantombuster. Account-first lead generation still exists for direct target-company lookups.
-
-When the output `mode` is `fallback`, the leads are modeled contacts for workflow testing, not verified real contacts. A real provider path should return `mode: "real"` using the same JSON shape.
-
-All non-auth commands require a logged-in CLI session. This gives you one identity model across Salesprompter app, CLI, and Chrome extension.
-
-Global output flags:
-
-- `--json`: compact machine-readable JSON (optimized for agent/LLM parsers)
-- `--quiet`: suppress successful stdout payloads (errors still surface)
-
-## Auth and Session
-
-The CLI stores a local session file at `~/.config/salesprompter/auth-session.json` (or `SALESPROMPTER_CONFIG_DIR`).
+# Start the interactive wizard
+salesprompter
 
-```bash
-# Preferred path: browser/device login
+# Login explicitly
 salesprompter auth:login
 
-# Fallback path: generate a short-lived CLI token in the Salesprompter app
-salesprompter auth:login --token "$SALESPROMPTER_TOKEN" --api-url "https://salesprompter.ai"
-
-# Verify active identity with backend
-salesprompter auth:whoami --verify
-
-# Clear local session
-salesprompter auth:logout
+# Verify your session
+salesprompter auth:whoami
 ```
 
-If your user belongs to multiple workspaces, the browser flow asks you to choose the workspace for that CLI session before returning to the terminal.
-
-Environment variables:
-
-- `SALESPROMPTER_API_BASE_URL`: override backend URL (default `https://salesprompter.ai`)
-- `SALESPROMPTER_CONFIG_DIR`: override local config dir
-- `SALESPROMPTER_ORG_ID`: optional org override for privileged Sales Navigator backfills
-- `SALESPROMPTER_SKIP_AUTH=1`: bypass auth guard (tests/dev only)
-- `INSTANTLY_API_KEY`: required for real `sync:outreach --target instantly`
-- `INSTANTLY_CAMPAIGN_ID`: default campaign id for Instantly sync
-- `SALESPROMPTER_INSTANTLY_BASE_URL`: override Instantly API base URL (tests/local proxies)
-- `NEXT_PUBLIC_SUPABASE_URL` or `SALESPROMPTER_SUPABASE_URL`: required for `salesnav:ensure-count` and for CLI-managed Sales Navigator exports
-- `SUPABASE_SERVICE_ROLE_KEY`: required for `salesnav:ensure-count` and for CLI-managed Sales Navigator exports
-- `LINKEDIN_SESSION_COOKIE_ENCRYPTION_KEY` or `EXTENSION_AUTH_SECRET` or `CLERK_SECRET_KEY`: required for Sales Navigator export and crawl commands that launch exports
-- `SALESPROMPTER_LINKEDIN_SESSION_EXCLUDED_EMAILS`: optional comma-separated emails to keep out of CLI-managed Sales Navigator rotation
-- `SALESPROMPTER_LINKEDIN_SESSION_EXCLUDED_HANDLES`: optional comma-separated LinkedIn handles to keep out of CLI-managed Sales Navigator rotation
-- `SALESPROMPTER_CLI_MANAGE_LINKEDIN_SESSIONS=0`: optional test or legacy fallback override; when omitted, the CLI claims, rotates, and preflights Sales Navigator session cookies before export launch
-- `GOOGLE_SERVICE_ACCOUNT_KEY`: required for `salesnav:ensure-count`
-- `BIGQUERY_PROJECT_ID`: optional when the Google service-account JSON already includes `project_id`
-
-App compatibility:
-
-- Salesprompter app should expose `/api/cli/auth/device/start`, `/api/cli/auth/device/poll`, and `/api/cli/auth/me`.
-- `salesprompter auth:login` uses browser/device login and prints the verification URL plus code before polling.
-- `POST /api/cli/auth/token` remains the fallback path when browser/device login is disabled or unavailable.
-
-Fallback command:
+## Common commands
 
 ```bash
-salesprompter auth:login --token "<token-from-app>" --api-url "https://salesprompter.ai"
-```
-
-## Why this shape works for humans and LLMs
+# Product/category to leads workflow
+salesprompter salesnav:from-product-category --input "https://www.linkedin.com/company/example/"
 
-- Every command reads and writes plain JSON.
-- Output is machine-readable and composable (`--json` for compact transport).
-- The top-level use cases map ambiguous prompts like "determine the ICP of deel.com" into explicit command paths.
-- Domain contracts are explicit and validated with `zod`.
-- External integrations are behind narrow provider interfaces.
-- Lead generation reports which provider and mode produced the result.
-- Workflow bottlenecks become inspectable artifacts instead of hidden Pipedream state.
-- Real prospect lookup can be normalized straight into the CLI lead schema with `--lead-out`.
+# Build Instantly-ready Deel outreach batches with German vs English splits
+salesprompter leadlists:deel-outreach:bq --market global --out-dir ./data/deel-outreach
 
-## Commands
+# Export the Supabase Sales Navigator Deel corpus into German vs English backlog files
+salesprompter salesnav:deel-locale-export --org-id "<org-id>" --out-dir ./data/deel-salesnav
 
-```bash
-salesprompter icp:define --name "EU SaaS RevOps" \
-  --description "RevOps and sales leaders in European growth-stage software companies" \
-  --industries "Software,Financial Services" \
-  --company-sizes "50-199,200-499" \
-  --regions "Europe" \
-  --countries "DE,NL,GB" \
-  --titles "Head of Revenue Operations,VP Sales" \
-  --required-signals "recent funding,growing outbound team" \
-  --keywords "revenue operations,outbound,sales tooling" \
-  --out ./data/icp.json
-
-salesprompter auth:login
-salesprompter auth:whoami --verify
-salesprompter --json salesnav:from-product-category --input deel.com --dry-run
-salesprompter salesnav:from-product-category --input deel.com
-# Historical fallback only. Resumes from prior CLI historical backfill runs unless you pass --start-offset.
-salesprompter salesnav:ensure-count --target-count 200000 --org-id "$SALESPROMPTER_ORG_ID"
+# Run a Sales Navigator crawl from a query URL
 salesprompter salesnav:crawl --query-url "https://www.linkedin.com/sales/search/people?query=..."
-salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
-salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json
-salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json
-salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json
-salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"
-salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID" --apply
-salesprompter icp:from-historical-queries:bq --vendor deel --market dach --out ./data/deel-icp-historical.json --report-out ./data/deel-historical-report.json
-salesprompter leadlists:funnel:bq --vendor deel --market dach --out ./data/deel-leadlists-funnel.json
-salesprompter leadlists:direct-export:bq --vendor deel --market dach --limit 20000 --out-dir ./data/direct-path --sql-out ./data/direct-path/deel-direct-dach.sql
-salesprompter domainfinder:backlog:bq --market dach --out ./data/deel-domainfinder-backlog.json
-salesprompter domainfinder:candidates:bq --market dach --limit 500 --out ./data/domain-candidates.json --sql-out ./data/domain-candidates.sql
-salesprompter domainfinder:input-sql --market dach --out ./data/domainFinder_input_v2.sql
-salesprompter domainfinder:select --in ./data/domain-candidates.json --out ./data/domain-decisions.json
-salesprompter domainfinder:audit --in ./data/domain-decisions.json --out ./data/domain-audit.json
-salesprompter domainfinder:compare-pipedream --in ./data/domain-candidates.json --out ./data/domain-comparison.json
-salesprompter domainfinder:audit-existing:bq --market dach --out ./data/domain-existing-audit.json
-salesprompter domainfinder:audit-delta --before ./data/domain-existing-audit-before.json --after ./data/domain-existing-audit-after.json --out ./data/domain-existing-audit-delta.json
-salesprompter domainfinder:repair-existing:bq --market dach --mode conservative --limit 5000 --out ./data/domain-repair.sql --trace-id salesprompter-cli-repair-dach
-salesprompter domainfinder:writeback-sql --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
-salesprompter domainfinder:writeback:bq --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
-salesprompter domainfinder:run:bq --market dach --limit 500 --out-dir ./data/domainfinder-run --trace-id salesprompter-cli-dach-20260308
-salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --out ./data/leads.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
-salesprompter leads:enrich --in ./data/leads.json --out ./data/enriched.json
-salesprompter leads:score --icp ./data/icp.json --in ./data/enriched.json --out ./data/scored.json
-salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100
-salesprompter queries:analyze:bq --search-kind sales-people --include-function "Human Resources" --out ./data/hr-query-report.json
-salesprompter sync:crm --target hubspot --in ./data/scored.json
-salesprompter sync:outreach --target instantly --in ./data/scored.json
-```
-
-## Domain Finder Migration
-
-The original Pipedream `domainFinder` workflow was doing three things:
-
-1. fetch a small input set from BigQuery
-2. ask OpenAI / Hunter for candidate domains
-3. pick a domain and write it back
-
-The CLI now models that logic directly and improves it:
 
-- `domainfinder:backlog:bq` measures whether the backlog is being starved before enrichment
-- `domainfinder:candidates:bq` fetches real candidate rows from BigQuery for backlog companies
-- `domainfinder:input-sql` generates a replacement input view driven by `linkedin_companies`, not `leadPool_new`
-- `domainfinder:select` applies deterministic domain selection rules
-- `domainfinder:audit` turns decisions into a review queue and writeback summary
-- `domainfinder:compare-pipedream` quantifies how often the old selector would disagree with the improved selector
-- `domainfinder:audit-existing:bq` measures current warehouse-visible mismatches and bad chosen domains
-- `domainfinder:audit-delta` compares two audit snapshots and reports metric deltas
-- `domainfinder:repair-existing:bq` generates (and optionally executes) targeted repair writes with selectable mode:
-  - `conservative`: only missing/blacklisted chosen domains
-  - `aggressive`: missing/blacklisted plus all mismatches
-  - `mismatch-only`: only mismatched chosen domains
-- `domainfinder:writeback-sql` emits conservative SQL for `domainFinder_output`
-- `domainfinder:writeback:bq` can execute that writeback in BigQuery when explicitly asked
-- `domainfinder:run:bq` runs the full candidate -> decision -> audit -> writeback pipeline and stores all artifacts
-
-Improved selection policy:
-
-1. prefer `domain_linkedin` when present and not blacklisted
-2. otherwise prefer `website_linkedin` root domain when present and not blacklisted
-3. otherwise choose the non-blacklisted candidate with the highest Hunter email count
-4. otherwise fall back to the first non-null candidate
-
-This removes the earlier failure mode where OpenAI or Hunter could override a good LinkedIn domain purely because of a higher Hunter count.
-
-Writeback policy:
-
-- write to `SalesPrompter.domainFinder_output`, which is the source feeding `linkedin_companies.domain`
-- exclude `no-domain` decisions
-- exclude blacklisted domains from generated writeback SQL
-- preserve batch provenance through `trace_id`
-
-## Development
-
-```bash
-npm install
-npm run build
-node ./dist/cli.js --help
-npm test
+# Check crawl status
+salesprompter salesnav:crawl:status --job-id "<job-id>"
 ```
 
-BigQuery project selection:
-
-- The CLI runs `bq query` with `--project_id` from `BQ_PROJECT_ID`.
-- Fallback order: `BQ_PROJECT_ID` -> `GOOGLE_CLOUD_PROJECT` -> `GCLOUD_PROJECT` -> `icpidentifier`.
-
-## Real Deel Flow
+## Output modes
 
-For Deel as the vendor you sell for, do not use `--domain deel.com`. That path targets contacts at Deel itself.
+- `--json` for machine-readable output
+- `--quiet` to suppress successful payload output
 
-Use this path instead:
+## Notes
 
-1. `salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json`
-2. `salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json`
-3. `salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json`
-4. `salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json`
-5. `salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"`
-6. Add `--apply` only when the dry-run output looks correct.
+- Use your own authorized LinkedIn / Sales Navigator access.
+- Respect LinkedIn and provider terms.
+- The CLI is designed for interactive users and agent-assisted workflows.
 
-## Next integrations
+## Links
 
-- Replace `HeuristicCompanyProvider` with a real account lookup provider.
-- Replace `HeuristicPeopleSearchProvider` with Apollo, Clay, LinkedIn, or custom people-data providers.
-- Replace `HeuristicEnrichmentProvider` with enrichment APIs such as Clearbit, FullEnrich, or custom LLM workflows.
-- Replace `DryRunSyncProvider` with real HubSpot, Salesforce, Pipedrive, Instantly, Apollo, or Outreach clients.
-- Add provider selection and credentials for a first real `--domain deel.com` workflow.
-- Replace configurable `bq` field mapping with a typed adapter per warehouse schema.
-- Add a real candidate-fetch command that reads domain candidates from BigQuery and feeds them into `domainfinder:select`.
+- Docs: https://salesprompter-cli.vercel.app
+- App: https://salesprompter.ai
+- Repository: https://github.com/danielsinewe/salesprompter-cli