starcovery

Official Starcovery CLI. Search creators, manage lists, export CSV, read credits, and manage API keys — same product surface as the dashboard and MCP.

Install

npm install -g starcovery
# or
bunx starcovery --help
npx starcovery --help

Requires Node.js 24+.

Auth

Search works without a key: 50 free searches per UTC day while signed out. A credential unlocks lists and credits; when the prepaid balance is empty, identified callers get 100 free searches per day. auth register mints an agent access token (lists/credits work); minting or revoking durable API keys still needs a human key from Settings → API keys.

Agents (no human in the loop):

starcovery auth register

That runs auth.md anonymous registration, exchanges the assertion for an access token, and saves it to ~/.config/starcovery/config.json.

Humans — mint a key at starcovery.com (Settings → API keys):

export STARCOVERY_API_KEY=sk_...
# or
starcovery auth set sk_...

Optional: STARCOVERY_BASE_URL (default https://www.starcovery.com).

Machine payments (MPP)

After free credits, identified search returns HTTP 402 with a Payment challenge (MPP, Stripe SPT). Settle the challenge with your agent payment tooling, then retry:

starcovery search "running shoes" --payment '<credential>'
# or
export STARCOVERY_PAYMENT='...'

Identity still rides x-api-key (from auth register or STARCOVERY_API_KEY). See auth.md and openapi.json.

Commands

starcovery search "running shoes"
starcovery search "running shoes" --payment '<mpp-credential>'
starcovery auth register
starcovery list
starcovery list create "Prospects"
starcovery list show <listId>
starcovery list export <listId> > out.csv
starcovery credits
starcovery keys
starcovery auth

Bare commands are read-only. Mutations use explicit subcommands (create, add, remove, revoke, …).

Publishing (maintainers)

Releases are tagged cli-vX.Y.Z and published by .github/workflows/publish-cli.yml via npm Trusted Publishing (OIDC). See the workflow file and monorepo notes for the one-time npm setup.