salesprompter-cli 0.1.19 → 0.1.20

package/README.md

@@ -3,9 +3,11 @@
 `salesprompter-cli` is a JSON-first command line interface for running a practical sales workflow:
 
 - Authenticate via Salesprompter app backend
-- Define an ideal customer profile
-- Resolve a target account from a domain
-- Generate seed leads
+- 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
@@ -17,6 +19,9 @@ 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.
@@ -28,8 +33,8 @@ npx -y salesprompter-cli@latest
 ## Explicit guided path
 npx -y salesprompter-cli@latest wizard
 
-## Raw command surface for agents and scripts
-npx salesprompter-cli@latest --help
+## Primary raw command for agents and scripts
+npx -y salesprompter-cli@latest salesnav:from-product-category --input deel.com --dry-run
 ```
 
 Or install it globally:
@@ -42,40 +47,50 @@ 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 organizations, browser login asks which organization the CLI session should use.
+If your Salesprompter user belongs to multiple workspaces, browser login asks which workspace the CLI session should use.
 
 ## Prompt To Command
 
-If the user says something like "I need to determine the ICP of deel.com", there are two different meanings.
+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
 
-### 1. They want leads at Deel itself
+### "I sell for Deel and want the right people at similar companies"
 
-This means Deel is the target account.
+Start from the company, product, or category input:
 
 ```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
+salesprompter salesnav:from-product-category --input deel.com
 ```
 
-### 2. They sell for Deel and need Deel's ideal customer profile
+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.
 
-This means Deel is the vendor, not the target account.
+Preview the generated titles and first split queries before creating crawl jobs:
 
 ```bash
-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 --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
 ```
 
-### 3. They want the LLM to call the CLI directly
+### Historical warehouse fallback
 
-Use the same commands, but prefer machine-readable output:
+`salesnav:ensure-count` remains a historical backfill path, not the primary workflow:
 
 ```bash
-salesprompter --json icp:vendor --vendor deel --market dach
-salesprompter --json icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
-salesprompter --json leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --lead-out ./data/deel-leads.json
+salesprompter salesnav:ensure-count --target-count 200000 --org-id "$SALESPROMPTER_ORG_ID"
 ```
 
 ## Documentation
@@ -118,7 +133,7 @@ This CLI is not a standalone toy. It is a production integration surface for the
   - BigQuery-backed runs (`domainfinder:run:bq`, `domainfinder:audit-existing:bq`)
   - before/after delta checks (`domainfinder:audit-delta`)
 
-The current version is account-first. It resolves a company from a domain, then generates contacts for that account through provider interfaces. The default providers are still fallback heuristics, but the JSON contracts are now stable for real company and people-data integrations.
+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.
 
@@ -147,16 +162,25 @@ salesprompter auth:whoami --verify
 salesprompter auth:logout
 ```
 
-If your user belongs to multiple organizations, the browser flow asks you to choose the organization for that CLI session before returning to the terminal.
+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:
 
@@ -197,6 +221,11 @@ salesprompter icp:define --name "EU SaaS RevOps" \
 
 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"
+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