CLI

This guide covers signing in to the Starcovery CLI, searching creators, running thread turns, and managing campaigns, credits, API keys, contact reveal, and payments.

The CLI is the starcovery npm package. npx starcovery and bunx starcovery run it with no install. The CLI needs Node.js 24 or newer.

Bare auth, campaigns, credits, keys, and whoami only read. A change takes an explicit verb, such as create or delete.

Search without an accountCopy Anchor Link

npx starcovery search "slow morning coffee"

Unsigned search is free up to 100 uses per rolling 24 hours per IP, and an identified caller gets 200. A pre-claim agent token from starcovery auth register skips the daily grant and spends prepaid credits only. A search is one use, and a starcovery thread turn is one use plus one for each search it runs. JSON output includes each creator's link-in-bio URL as externalUrl when the search result has one. Table and CSV put that URL in the Link column.

The CLI waits up to 300 seconds for search, generate, and the creators read after a thread turn. Enrich and the thread turn itself wait until the api answers, and the api ends a request at 800 seconds. Each call holds the connection open until the result is ready.

Thread turnsCopy Anchor Link

starcovery thread "creators who post home coffee"
starcovery thread "only on Instagram" --thread <threadId>

One command opens a search thread and runs one turn, or continues the thread named with --thread. A pasted website address is read into a brief; anything else refines the creators on screen: a message that narrows returns a subset of them, a message that asks for more combines a new search with them, and only a message that replaces the search starts over. A question about the organization's campaigns, Lists, credits, or API keys is answered from read tools, and the turn changes none of them.

When the turn ends, the CLI writes the result to stdout: the thread id, the status, the settled brief, its filters, and the reply, followed by the creators of the thread result set as starcovery search prints them. The progress lines of the turn follow on stderr. JSON matches the turn result plus threadId, creators, and ticket. Pass the thread id back with --thread to continue the conversation. A refinement shows the set it built; the first brief runs one search for its creators, billed like starcovery search, and the thread stores the set, so reading it again is free.

The command needs a credential. The Model Context Protocol (MCP) tool thread_turn and POST /api/threads/{threadId}/turns run the same loop.

Agent signupCopy Anchor Link

For browser OAuth:

npx starcovery auth login

The command opens the browser, stores a refreshable OAuth credential, and binds it to the organization active during consent.

For agentic signup without a browser:

npx starcovery auth register

This follows the auth.md protocol, exchanges the assertion for an agent access token, writes ~/.config/starcovery/config.json, and installs the host skill with bunx skills when bun is on PATH, otherwise npx -y skills.

To hand the registered identity to a person, run this command with their email address:

npx starcovery auth claim <email>

Starcovery mails a claim link to that address. The person opens it, signs in with Google, and selects Claim This Account. The next CLI command then saves the claimed credential. If that command stops with a claim notice, run it again. The identity keeps its credits, campaigns, and history.

You can also pass credentials per call:

export STARCOVERY_ACCESS_TOKEN=<access_token>
starcovery search "running shoes" --access-token <access_token>

A person can mint a Settings API key in Settings > API Keys and save it with this command:

starcovery auth set <api_key>

Inspect the active credential and credit routing:

starcovery whoami

The output identifies the credential, user, and organization. It also shows whether the next search uses the user's free grant or the organization's prepaid credits.

Campaign and account commandsCopy Anchor Link

These commands manage campaigns, contact reveal, enrichment, thread turns, credits, and Settings API keys:

starcovery campaigns
starcovery campaigns create "Coffee" --goal "quiet morning coffee creators"
starcovery campaigns generate <id>
starcovery campaigns show <id>
starcovery search "coffee" --json | jq '.creators[0]' > creator.json
starcovery campaigns add <id> --json creator.json
starcovery campaigns export <id> > out.csv
starcovery campaigns update <id> --market-information 0
starcovery campaigns send <id>
starcovery campaigns fund <id>
starcovery contact reveal <profileId>
starcovery search "coffee" --enrich --json
starcovery search "coffee" --json > search.json
starcovery enrich --json search.json --format json
starcovery thread "creators who post home coffee"
starcovery credits
starcovery keys

Campaigns, contact reveal, credits, and thread turns need an access token or a Settings API key. keys needs a Settings API key; an agent access token gets 403.

campaigns fund requests funding for the accepted creators not yet funded, per person. The caller needs an owner or admin role in the organization; another member gets 403 organization_funding_forbidden. The campaign needs a contract, a market information answer, and at least one creator who accepted. Set the answer with --market-information on campaigns create or campaigns update. The answer decides when the campaign's name and pay per creator join the going rate, the list of campaigns and the typical pay other organizations and creators see, no earlier than the declassifying date, and takes one of these values:

• 0 adds them once funding is requested, with no platform fee.
• 1 to 18 holds them back that many months after the first funding request, for a fee of that many percent of the creator pool.
• never keeps them out, for a 20% fee.

The answer locks at the campaign's first funding request. After it, a campaigns update that changes the answer fails with 409 market_information_locked.

Search results omit contact addresses until starcovery contact reveal. That command spends 1 prepaid credit the first time this organization reveals that profile. Later reveals do not charge again.

Plain starcovery search --json output matches GET /api/search (creators, query, and the enrichment ticket). starcovery search --enrich --json adds an analysis object; starcovery enrich --json prints that shortlist analysis (niche, celebrity, evidence, signal).

When a search asks for paymentCopy Anchor Link

Identified search past the daily grant spends prepaid credits and returns 402 when the organization has no prepaid credits left. The CLI writes a summary line to stderr, with the checkoutUrl when the body has one, then the Payment challenge when the 402 includes one, then the 402 JSON body, and exits with code 1.

Pay in one of two ways. Either way, one payment adds 10 prepaid credits for $0.50 to the organization credit ledger.

• Checkout: an owner or admin of the organization gets checkoutUrl in the body. Pay that Stripe Checkout session, then run the same search again with an access token or API key.
• Machine payment: for an owner or admin of the organization, the 402 includes a WWW-Authenticate: Payment challenge. The challenge uses the Machine Payments Protocol (MPP) over a Stripe Shared Payment Token (SPT). Settle it, then run the same search again with the payment credential in --payment or STARCOVERY_PAYMENT.

starcovery search "running shoes" --payment <credential>

The CLI sends the payment credential in the Payment-Authorization header and keeps the access token or API key on Authorization or x-api-key. The credits go to that identity's organization, so without an access token or API key the CLI refuses the payment credential before any request. Only search takes --payment; a thread turn settles no payment. A payment credential that is unreadable or minted for a different caller or organization settles nothing, and the search answers with a new 402 challenge.

To see the 402 without paying, call GET /api/search?q=test&force_payment=1 with an access token or API key. The response contains the 402 body and, for an owner or admin, the challenge, creates no Checkout session, and settles nothing.

For more about payments, see Credits and payments and the agent protocol.

CLI and web parityCopy Anchor Link

Does the CLI expose a smaller API than the web?Copy Anchor Link

Yes, in places. Search, thread turns, shortlist enrichment, contact reveal, campaigns, credits, and keys run the same operations as the web and MCP. Lists, campaign attachments, and handle claims have no CLI command. Account checkout and the claim ceremony stay on the web. Search, generate, enrich, and thread turns return their result in the same call.