@series-a/cli

A command-line interface to the AdvisorOS platform — drive leads, campaigns, sequences and agents from your terminal. Built on top of the /agent-api M2M router, so anything the CLI does is auditable and workspace-scoped.

Install

# Run without installing — always fetches latest
npx @series-a/cli@latest --help

# Pin a version (recommended for CI)
npx @series-a/[email protected] --help

# Or install globally
npm i -g @series-a/cli
advisoros --help

Requires Node.js ≥ 20.

Releases are tagged cli-vX.Y.Z in the repo and published to npm with provenance. See CHANGELOG.md.

1. Get an API key

1. Sign in to AdvisorOS.
2. Open Settings → API Keys.
3. Click New key → choose Workspace scope (recommended).
4. Copy the key — you won't see it again.

The CLI quickstart card on that page shows a copy-paste npx command pre-filled with your workspace ID.

Admin keys (cross-workspace) also work but are intentionally restricted. Default to workspace keys.

2. Log in

npx @series-a/cli@latest login
# Prompts for API key + workspace ID (the 6-char slug, e.g. dmw9wj)

Multiple workspaces?

advisoros login --profile acme        # save as "acme"
advisoros leads list --profile acme   # use the named profile

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.

advisoros whoami
advisoros profiles
advisoros logout --profile acme

3. Command reference

Global flags (work on every subcommand):

| 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

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 verify <id>

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).

Campaigns

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>

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

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 job <jobId>

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.

Examples

Spin up a campaign from a fresh CSV:

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-...

Tail a long-running agent job:

JOB=$(advisoros agents run lead-intelligence --input '{}' --json | jq -r '.run.job_id')
watch -n 5 "advisoros agents job $JOB --json | jq '{status,progress}'"

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Generic failure (error in JSON response or thrown). Stderr contains the message. |

Programmatic use

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)

cd tools/cli
npx changeset                                            # describe the change
npm run version                                          # 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

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.

Full API reference

See docs/agent-api.md for the underlying /agent-api envelope.