CLI
By Starcovery. Updated .
Run every Starcovery API operation from a terminal, one command per operation, named as the API names it, printing the API answer unchanged.
The Starcovery CLI runs the Starcovery API from a terminal. Each operation the OpenAPI description lists is one command, starcovery <group> <operation>, with the group and the operation named as the API names them, and one flag for each path, query, header, and body field of that operation.
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.
Search without an account
npx starcovery search searchCreators --q "slow morning coffee"The command sends GET /api/search with the brief in q and prints the answer. Unsigned search is free up to 100 uses per UTC day per IP, and an identified caller gets 200, with the members of one organization sharing at most 200 between them.
Commands and flags
starcovery --help lists the groups, starcovery <group> --help lists the operations of a group, and starcovery <group> <operation> --help lists the flags of an operation. The API reference describes each operation, its fields, and its answers.
- A path, query, or header field takes its value as text, such as
--campaignId <CAMPAIGN>. - A body field takes its value as text when the field is text, and as JSON otherwise, such as a list or an object.
- An operation whose body is not an object of named fields, such as
tools callTool, reads its body from stdin. - An operation that accepts its body in more than one file type, such as
campaigns uploadCampaignAttachment, takes the type of the body from stdin in--content-type.
starcovery search parseSearchQuery --q "micro coffee creators in Canada"
starcovery search searchCreators --q "slow morning coffee" --platform ig --country us,ca
starcovery campaigns listCampaigns
starcovery campaigns createCampaign --name "Coffee" --goal "quiet morning coffee creators"
starcovery campaigns generateCampaignMatches --campaignId <CAMPAIGN>
starcovery campaigns exportCampaign --campaignId <CAMPAIGN> > out.csv
starcovery campaigns uploadCampaignAttachment --campaignId <CAMPAIGN> --filename brief.pdf --content-type application/pdf < brief.pdf
starcovery billing billingState
starcovery keys listKeys
starcovery tools listTools
echo '{"name": "Dewlight Studio"}' | starcovery tools callTool --name rename_organizationOutput and exit codes
The CLI prints the API's answer unchanged. A 2xx answer goes to stdout, and the CLI exits 0. Any other answer goes to stderr, and the CLI exits 1, so a script reads the API's error document, such as out_of_credits, as the API sent it. An answer that streams, such as search enrichShortlist, prints as it arrives.
A command the CLI cannot parse, such as an unknown operation or a missing required flag, prints the help of that command with the error, sends nothing, and exits 1.
Credentials
Set STARCOVERY_TOKEN to a Settings API key, and the CLI sends it as Authorization: Bearer on every request. A person creates the key in Settings > API Keys.
export STARCOVERY_TOKEN=<TOKEN>
starcovery whoami whoamiwhoami whoami shows the credential, the user and organization it resolves to, and whether the next search uses the daily grant or the organization's prepaid credits. Without STARCOVERY_TOKEN, a request carries no credential, which search accepts and every operation that acts for an organization answers with 401.
STARCOVERY_BASE_URL sends requests to an origin other than https://www.starcovery.com.
To install the host skill for Cursor, Claude Code, and Codex, run the installer in Authentication.
When the organization runs out of credits
Identified search past the daily grant spends prepaid credits, and the API answers 402 out_of_credits when the organization has no prepaid credits left. The CLI prints that answer on stderr and exits 1. An owner or admin buys a credit pack in Billing settings, and then the same command runs again.
For more about credits, see Pay for API calls without a subscription.
CLI and API parity
Does the CLI expose a smaller API than the web?
No. The CLI has one command for each operation of the API, and CI fails a change that adds an operation without its command. tools callTool runs every catalog tool that MCP and the assistant in the web app use, such as Lists, handle claims, and organization settings. A tool that changes an organization or an account answers next and url; open url in a browser signed in to Starcovery to confirm the change there.