@series-a/cli 1.3.0 → 1.3.2

package/README.md

@@ -1,183 +1,317 @@
-# Setu CLI (internal)
+# @series-a/cli
 
-Build claimable practice and dentist profiles from the command line.
+A command-line interface to the AdvisorPro platform — drive leads, campaigns, sequences and agents from your terminal. Built on top of the [`/agent-api`](https://github.com/series-a/advisoros/blob/main/docs/agent-api.md) M2M router, so anything the CLI does is auditable and workspace-scoped.
+
+---
 
 ## Install
 
 ```bash
-cd packages/cli && npm link      # gives you the `setu` command
-setu login                       # paste the internal CLI key
+# Run without installing — always fetches latest
+npx @series-a/cli@latest --help
+
+# Pin a version (recommended for CI)
+npx @series-a/cli@0.1.0 --help
+
+# Or install globally
+npm i -g @series-a/cli
+advisoros --help
 ```
 
-The key is the `SETU_CLI_API_KEY` secret from the Setu backend. It is stored at
-`~/.config/setu/config.json` (chmod 600). You can also set `SETU_CLI_API_KEY`
-and `SETU_API_URL` as environment variables in CI.
+Requires **Node.js ≥ 20**.
 
-## Build one profile
+> Releases are tagged `cli-vX.Y.Z` in the repo and published to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements). See [`CHANGELOG.md`](./CHANGELOG.md).
 
-```bash
-setu practice create --url https://smiledental.co.uk
-setu practice create --name "Smile Dental" --town Portsmouth
-setu practice review <draft-id>
-setu practice publish <draft-id>
-```
+## 1. Get an API key
 
-`create` scrapes the practice website (services, pricing, hours, team, images),
-pulls their Google listing (address, phone, rating, reviews, opening hours) and
-returns a readiness score. Nothing is public until `publish`.
+1. Sign in to AdvisorPro.
+2. Open **Settings → API Keys**.
+3. Click **New key** → choose **Workspace** scope (recommended).
+4. Copy the key — you won't see it again.
 
-`publish` creates an **unclaimed** listing: it appears in patient search with an
-"Unclaimed" badge, ranked below live subscribed practices, with enquiry capture
-instead of booking. It also seeds any clinicians the AI detected (skip with
-`--no-dentists`).
+The **CLI quickstart** card on that page shows a copy-paste `npx` command pre-filled with your workspace ID.
 
-## Bulk import
+> Admin keys (cross-workspace) also work but are intentionally restricted. Default to workspace keys.
 
-CSV with any of these columns: `name, website, town, postcode, email, phone`.
+## 2. Log in
 
 ```bash
-setu practice import practices.csv --publish
+npx @series-a/cli@latest login
+# Prompts for API key + workspace ID (the 6-char slug, e.g. dmw9wj)
 ```
 
-Rows are processed one at a time (Firecrawl / Google rate limits) and failures
-are listed at the end so you can retry them.
+### Admin login
 
-## Claim links
+Admin keys (`advos_admin_…`) are detected automatically — no workspace prompt:
 
 ```bash
-setu practice claim-link <practice-id>
-setu status                       # every seeded profile and its claim state
-setu status <practice-id>         # one profile plus its claim attempts
-setu status <profile-id> --full   # every field, photos, prices, services, clinicians
-setu status --dentist             # list clinicians instead of practices
+advisoros login --admin
+# ✓ Logged in as admin profile "default" — N workspaces reachable
+
+advisoros workspaces list                       # admin-only, no workspace needed
+advisoros campaigns list --workspace dmw9wj     # pass workspace per command
+advisoros whoami                                # shows scope: admin (cross-workspace)
 ```
 
-Send the claim link in outreach. The practice signs in, and is verified either
-by their email domain matching their website, or by a code sent to the public
-contact address on their Google listing. On success the profile transfers to
-them, pre-filled, and they continue through the normal onboarding and
-subscription flow.
+Multiple workspaces?
+
+```bash
+advisoros login --profile acme        # save as "acme"
+advisoros leads list --profile acme   # use the named profile
+```
 
-## Reviewing claims
+Config is stored at `~/.advisoros/config.json` with mode `0600`. You can also use env vars: `ADVISOROS_API_KEY`, `ADVISOROS_WORKSPACE_ID`, `ADVISOROS_PROFILE`, `ADVISOROS_BASE_URL`.
 
 ```bash
-setu claims                        # pending claims + unclaimed profiles by readiness
-setu claims --ready                # only profiles ready to promote
-setu claims --status all           # every claim, any status
-setu claims show <claim-id>        # claimant, method, attempts, target profile
-setu claims approve <claim-id>     # transfer the profile to the claimant
-setu claims decline <claim-id> --reason "Not the practice owner"
+advisoros whoami
+advisoros profiles
+advisoros logout --profile acme
 ```
 
-Approving a practice claim makes the claimant the owner, adds an owner
-membership and marks the practice's clinicians as claimed. A claim can only be
-approved once the claimant has signed in, so there's an account to transfer to.
+## 3. Command reference
 
-## Clinicians
+Global flags (work on every subcommand):
 
-```bash
-setu dentist create --name "Dr Jane Roe" --practice <id> --profile-url https://…/team/jane \
-  --photo https://…/jane.jpg --gallery "https://…/a.jpg,https://…/b.jpg" \
-  --phone 02392000000 --website https://… --booking https://…/book
+| Flag | Description |
+|---|---|
+| `--json` | Emit raw JSON instead of formatted tables. |
+| `-w, --workspace <id>` | Override the workspace from your profile. |
+| `-p, --profile <name>` | Pick a saved profile. |
+| `--api-key <key>` | Override the saved API key. |
+
+### Leads
 
-setu practice list --limit 100 --search "smile"
-setu dentist  list --practice <practice-id>
-setu dentist  status <dentist-id> --full
+```bash
+advisoros leads list [--status new] [--persona founder] [--search acme] [--limit 50]
+advisoros leads get <id>
+advisoros leads set-status <id> <new|engaged|won|lost>
+advisoros leads import --file leads.csv [--persona founder]
+advisoros leads import-from <source> [--query ...] [--post <url>] [--file <path>] [--audience <name>] [--campaign <id>] [--limit 50] [--no-enrich]
+advisoros leads import-status <jobId>
+advisoros leads update <id> [--name ...] [--title ...] [--company ...] [--email ...] [--linkedin ...] [--persona ...] [--score ...] [--status ...] [--notes ...]
+advisoros leads delete <id>
+advisoros leads verify <id>
 ```
 
-## Flags
+`leads import` accepts CSV (header row), JSON array, or JSONL. Upserts on `(workspace_id, linkedin_url)`. Bulk requests are auto-chunked at 200/call (server cap: 500/call).
 
-`--json` for machine-readable output, `--operator "Your Name"` to attribute
-seeded profiles to you.
+`leads import-from` runs any of the import sources in **Get Leads → Import Leads**:
 
-## Reliability
+| source | required params | what it does |
+|---|---|---|
+| `linkedin_search` | `--query` | keyword / title / company people search via Unipile |
+| `company_search` | `--query` | LinkedIn company search |
+| `post_reactors` | `--post <url>` | everyone who reacted to a LinkedIn post |
+| `paste_profiles` | `--file <path>` | name + LinkedIn URL lines; rest is enriched |
+| `csv` | `--file <path>` | same CSV parser the UI uses |
+| `heyreach` | `--file <path>` `--campaign <id>` | HeyReach campaign CSV, statuses preserved |
+| `sales_nav_url` | `--url <sales-nav-search-url>` | queues a background Sales Navigator import, drip-fed inside the LinkedIn read limits |
+| `sales_nav_keywords` | `--query` | same background queue, from Sales Navigator keywords |
 
-- Every request has a timeout (`SETU_TIMEOUT_MS`, default 240s) and retries
-  transient failures (network drops, 429, 5xx) with exponential backoff
-  (`SETU_RETRIES`, default 3). `Retry-After` is honoured.
-- `--verbose` prints retry attempts and stack traces.
-- `setu logout` removes the stored key from this machine.
-- Unknown commands and failed bulk imports exit non-zero (safe for scripts/CI).
+All sources accept `--audience` to attach leads to a segment (created if missing). LinkedIn-backed sources run at bulk read priority so live campaigns are not starved. Long-running imports return a `job_id`; poll with `advisoros leads import-status <jobId>`.
 
-## Bulk import
+Sales Navigator sources do not run inline — they create a **scheduled import** that the
+cap-aware scheduler drip-feeds over hours or days:
 
 ```bash
-setu practice import practices.csv --dry-run            # validate only
-setu practice import practices.csv --publish \
-  --concurrency 3 --out results.json                    # run
-setu practice import practices.csv --resume results.json # retry failures only
+advisoros leads import-from sales_nav_url --url "https://www.linkedin.com/sales/search/people?..." \
+  --limit 500 --audience "Q3 ICP" --priority high
+advisoros leads import-schedules
+advisoros leads import-schedule pause|resume|cancel <id>
 ```
 
-Rows need either a `website`/`url`, or a `name` plus `town`/`city`; anything
-else is reported and skipped before any API call is made.
+Cancelling keeps the leads already imported.
 
-## Editing seeded profiles
+### Campaigns
 
 ```bash
-setu practice update <practice-id> --fields                     # what you can set
-setu practice update <practice-id> --set tagline="Gentle care" --set emergency_available=true
-setu dentist  update <dentist-id>  --set bio="20 years in implants"
+advisoros campaigns list [--status active]
+advisoros campaigns show <id>
+advisoros campaigns create --name "Founder Pitch Club" \
+                           --sequence <sequenceId> \
+                           --senders acc_a,acc_b \
+                           --daily-limit 25
+advisoros campaigns add-leads <campaignId> --lead-ids id1,id2,id3
+advisoros campaigns add-leads <campaignId> --file lead-ids.txt
+advisoros campaigns launch <id>
+advisoros campaigns pause  <id>
+advisoros campaigns resume <id>
+advisoros campaigns rename <id> "New name"   # rename without touching other settings
+```
+
+`launch` flips status to `active` — the `enforce_campaign_char_limits` trigger validates every step's copy against LinkedIn limits before allowing the transition.
+
+### Sequences / Inbox / Content / Agents / Meetings / Newsletter / Integrations
+
+```bash
+advisoros sequences list
+advisoros sequences show <id>
+
+advisoros inbox threads [--campaign <id>] [--lead <id>] [--needs-attention] [--limit 50]
+
+advisoros content list [--status published] [--type post] [--search ...]
+advisoros content show <id>
+advisoros content publish <id>
+
+advisoros agents list
+advisoros agents run <name> --input '{"foo":"bar"}'
+advisoros agents trigger <name> --input '{"foo":"bar"}'
+advisoros agents history [--agent <name>] [--days 30] [--limit 50]
+advisoros agents job <jobId>
+
+advisoros meetings list [--limit 50]
+advisoros meetings transcripts [--provider fireflies|roam] [--since 2026-01-01] [--limit 50]
+advisoros meetings transcript <transcriptId> [--original | --mode anonymised|original]
+
+advisoros newsletter list
+advisoros newsletter create --subject "Weekly roundup" --body "<html>..." [--preview-text "..."]
+advisoros newsletter edit <id> [--subject ...] [--body ...] [--preview-text ...] [--status draft|scheduled]
+advisoros newsletter delete <id>
+
+advisoros integrations status
+advisoros integrations check <platform>
+```
+
+> **Heads-up:** `inbox send`/`reply` are intentionally **not** in v1. Outbound goes through `campaigns launch` (sender resolution + char limits + per-sender daily budget). For one-off DMs, use the web inbox.
+
+`meetings transcript` returns anonymised text by default, once anonymisation is ready; otherwise metadata is returned with an explicit reason. Add `--original` to get the original text and speaker identities — your key needs this permission (all unrestricted keys already have it) and every original read is audited.
+
+`integrations status` is read-only and never returns credentials. `integrations check <platform>` runs a live health probe for the requested platform (e.g. `linkedin_tool`).
 
-# Booking / website link shortcuts
-setu practice update <practice-id> --booking https://clinic.co.uk/book
-setu dentist  update <dentist-id>  --booking https://clinic.co.uk/book --website https://clinic.co.uk
+### Obsidian vault mirror (`kb`) — one-way
+
+```bash
+advisoros kb link ./client-vault --workspace dmw9wj
+advisoros kb status ./client-vault           # dry-run preview
+advisoros kb pull ./client-vault             # mirror notes + graph entities
+advisoros kb pull ./client-vault --preserve-local
 ```
 
-Lists take comma-separated values, e.g. `--set services="Implants,Whitening"`.
+One-way push, AdvisorPro → Obsidian. Markdown notes with frontmatter, `[[wikilinks]]` and an
+`## Entities` block, plus `Entities/<Type>/*.md` for graph nodes. Local edits are overwritten unless
+`--preserve-local` is used (remote copy lands as `<slug>.remote.md`). Nothing is pushed back.
+
+
+## Examples
 
-Everything on the practice profile settings screen is settable. The few values that
-live in the nested profile record — positioning, amenities, default currency — use
-`--set-enrichment`:
+**Spin up a campaign from a fresh CSV:**
 
 ```bash
-setu practice update <practice-id> --set-enrichment positioning.summary="Calm, modern care in Leeds"
-setu practice update <practice-id> --set-enrichment amenities="Wi-Fi,Free parking,Step-free access"
-setu practice update <practice-id> --set-enrichment positioning.archetype=boutique
-setu practice update <practice-id> --set parking_info="Two-hour free bay on site" \
-  --set accessibility="Step-free,Hearing loop" --set languages="English,Polish"
+advisoros leads import --file ./prospects.csv --persona founder
+advisoros leads list --persona founder --limit 200 --json \
+  | jq -r '.leads[].id' > lead-ids.txt
+
+advisoros campaigns create --name "Q3 Founder Outreach" \
+  --sequence 1a2b3c4d-... --senders acc_milan --daily-limit 25
+# → ✓ Created campaign 8297f04d-...
+
+advisoros campaigns add-leads 8297f04d-... --file lead-ids.txt
+advisoros campaigns launch    8297f04d-...
 ```
 
-## Photos and logos
+**Tail a long-running agent job:**
 
 ```bash
-setu practice images <practice-id> --list
-setu practice images <practice-id> --add https://.../photo.jpg
-setu practice images <practice-id> --remove 2                   # by index, or pass the URL
-setu practice images <practice-id> --order "https://.../hero.jpg"   # move these to the front
-setu practice images <practice-id> --replace "https://a.jpg,https://b.jpg"
-setu practice images <practice-id> --logo https://.../logo.png
-setu dentist  images <dentist-id>  --logo https://.../headshot.jpg  # main photo
+JOB=$(advisoros agents run lead-intelligence --input '{}' --json | jq -r '.run.job_id')
+watch -n 5 "advisoros agents job $JOB --json | jq '{status,progress}'"
 ```
 
-Upload from your machine (or copy a remote image into Setu storage) instead of
-linking to someone else's server:
+## Safety rails
+
+Anything that stops sending, un-enrols leads or deletes data now asks first.
 
 ```bash
-setu practice images <practice-id> --upload ./reception.jpg
-setu practice images <practice-id> --upload-logo ./logo.png
-setu dentist  images <dentist-id>  --upload-logo https://.../headshot.jpg
+# Launch is a dry run until you confirm — preflight runs server-side.
+advisoros campaigns preflight 9884b9ec
+advisoros campaigns launch 9884b9ec            # shows blockers, changes nothing
+advisoros campaigns launch 9884b9ec --confirm  # actually launches
+
+# Destructive commands prompt; scripts must pass --yes.
+advisoros campaigns delete 9884b9ec --dry-run
+advisoros campaigns delete 9884b9ec --yes
+advisoros sequences delete-step 6b60d6ad --yes
 ```
 
-## Prices and services
+A campaign with no leads, no sequence, no steps or no sender account is
+**refused**, not silently activated. `--force` overrides once you know why.
+
+New commands: `campaigns preflight|archive|clone|delete|remove-leads`,
+`sequences delete|update-step|delete-step`.
+
+## Reading more than 200 rows
+
+List commands accept `--limit` up to 1000 and every list response carries
+`pagination` (`total`, `limit`, `offset`, `next_cursor`, `has_more`). If you ask
+for more than the maximum, the response says it was clamped instead of quietly
+truncating.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic failure (`error` in JSON response or thrown). Stderr contains the message. |
+
+## Programmatic use
+
+```js
+import { call } from "@series-a/cli/src/api.mjs";
+
+const { campaigns } = await call("campaigns", "list", { status: "active" }, {
+  apiKey: process.env.ADVISOROS_API_KEY,
+  workspaceId: "dmw9wj",
+});
+```
+
+## Troubleshooting
+
+- **401 Unauthorized** — key wrong / revoked / wrong base URL. Re-run `advisoros login`.
+- **403 not authorized for the requested workspace_id** — workspace-scoped key + `--workspace` to a different workspace. Use the matching key.
+- **CHAR_LIMIT_EXCEEDED on launch** — a sequence step exceeds LinkedIn limits (200 invitations / 8000 DMs / 1250 comments). Fix in web app.
+- **Network error** — check `ADVISOROS_BASE_URL` if you're pointing at a non-default deployment.
+
+## Releasing (maintainers)
 
 ```bash
-setu practice pricing <practice-id> --list
-setu practice pricing <practice-id> --set "Dental implant=1200" --set "Whitening=300-450"
-setu practice pricing <practice-id> --remove "Whitening"
-setu dentist  pricing <dentist-id>  --set "Hygiene visit=75"
-setu practice update <practice-id> --set services="Implants,Whitening,Invisalign"
+cd tools/cli
+npx changeset                                            # describe the change
+npm run version-packages                                 # bump package.json + CHANGELOG.md
+git commit -am "chore(cli): release v$(node -p "require('./package.json').version")"
+git tag "cli-v$(node -p "require('./package.json').version")"
+git push --follow-tags
+# → .github/workflows/cli-release.yml publishes to npm with provenance
 ```
 
-Practice prices update the practice's treatment list too. Dentist prices are
-saved as individual treatment rows shown on the clinician's profile.
+`NPM_TOKEN` must be set in the repo's GitHub Actions secrets (automation token with publish access to the `@series-a` org).
+
+## Roadmap (v1.1)
+
+- `inbox send` / `inbox reply` with explicit `--confirm` + per-sender budget enforcement.
+- `agents tail <jobId>` (SSE).
+- `admin workspaces …` (admin keys only).
+- Single-binary builds via `pkg`.
 
-## Removing seeded profiles
+## Full API reference
+
+See [`docs/agent-api.md`](../../docs/agent-api.md) for the underlying `/agent-api` envelope.
+
+
+
+## Admin keys
+
+Admin keys (`advos_admin_…`) are authorised by the key itself — they do **not** need an
+`agent_workspace_bindings` row. `agent_name` is an audit label only.
 
 ```bash
-setu practice delete <practice-id> --unpublish   # hide from patients
-setu practice delete <practice-id>               # delete (unclaimed only)
-setu dentist  delete <dentist-id> --unpublish
-setu dentist  delete <dentist-id>
+advisoros login --admin --profile ops     # no workspace prompt; prints reachable workspace count
+advisoros whoami --profile ops            # scope: admin (cross-workspace) + reachable count
+advisoros workspaces list --profile ops   # every reachable workspace (paginated, up to 1000)
+advisoros analytics overview --workspace dmw9wj --profile ops
 ```
 
-Claimed or user-owned profiles are always refused.
+Caller identity is overridable: `--as-agent <name>` on any command, `ADVISOROS_AGENT_NAME`
+in the environment, or the `agentName` stored on the profile at login (default `advisoros-cli`).
+
+Workspace-scoped keys are unchanged: they can only reach their own workspace (403 otherwise)
+and cannot use the `workspaces` resource. An agent without bindings now gets a typed 403
+explaining to use an admin key, instead of a 500.