Use the command-line tool

The searcherries command reads your Searcherries data in a terminal: AI visibility, stored AI answers with their judgments, competitors, cited URLs and domains, Google Search Console and Bing Webmaster Tools data, GA4 AI traffic and the action plan. It prints tables for you to read, or JSON for scripts and for AI coding agents such as Claude Code and Codex.

The tool is read-only. It calls the REST API, so it returns the same stored data and follows the same plan rules: the free plan reads projects, the summary, search performance, AI traffic and the action plan; AI answers, competitors and citations need Starter or Pro, an active trial counts.

Install

You need Node.js 20 or newer. Install the tool once:

npm install -g searcherries

To run it without installing, put npx in front of every command, for example npx searcherries projects.

Open MCP in Searcherries, go to the Other clients tab and create an access token. Copy it right away; it is shown once.
Run searcherries login and paste the token when asked. The token stays hidden while you paste it.
Run searcherries projects. Your projects are listed with their status and connected sources.

The tool checks the token before it saves it, in a file only your user account can read. searcherries logout removes the file; the token keeps working until you revoke it on the MCP page. In a scheduled job or CI, set the SEARCHERRIES_TOKEN environment variable instead of signing in.

Commands

Command	Returns
`projects`	Your projects with status, plan, last check and connected sources.
`summary`	A compact snapshot of one project: AI visibility, questions, competitors, cited domains, search, AI traffic and connections.
`answers`	Stored AI answers with how prominently the brand is named, sentiment, flags and cited URLs.
`search`	Google Search Console or Bing Webmaster Tools data: totals, top queries and pages, opportunities, trends, question-shaped queries, daily and monthly figures.
`competitors`	The brands AI platforms name: the ranking, one brand in detail, or the monthly history.
`citations`	The URLs or domains AI answers cite.
`traffic`	GA4 traffic from AI assistants and AI Overviews: sources, landing pages, daily and monthly figures.
`plan`	Prioritized next steps with dated evidence, for a business owner, a marketer or an SEO.
`api`	Any REST API endpoint, printed as JSON.
`status`	Which token is in use and how many requests are left this minute.

The commands that read one project take it as their first argument: the numeric id, the brand name, the domain or part of one, such as acme, acme.com or 123. Leave it out when your account has one project. Put quotes around a name that contains spaces.

searcherries <command> --help lists the options of a command and their allowed values. They match the parameters of the endpoint reference, written with dashes: --prominence-max sends prominence_max.

Examples

Find the questions where AI answers leave your brand out:

searcherries answers acme --prominence-max 1

Read the negative answers and drawbacks, with the answer text and the sentence behind each flag:

searcherries answers acme --only-flagged --include-answer-text

See how one competitor appears, then the monthly ranking:

searcherries competitors acme --competitor rival
searcherries competitors acme --dataset history

List Google queries with many impressions and few clicks over 90 days:

searcherries search acme --dataset opportunities --period 90d

Get the action plan for an SEO as JSON:

searcherries plan acme --audience seo --json

Scripts and AI agents

--json prints the API response without changes. Errors go to the error output (stderr), so a script that reads JSON from the standard output never receives an error message in its place. --all reads every page of a list and prints the rows as one response.

The tool waits and retries when the rate limit is reached, if the wait is a minute or less. Its exit code tells a script what happened:

Code	Meaning
`0`	The command succeeded.
`1`	The API or the network failed, the project was not found, or a parameter was rejected.
`2`	The command or an option was mistyped.
`3`	Nobody is signed in, or the token was rejected.
`4`	The command needs a Starter or Pro plan.

AI coding agents can run the tool in the terminal they already use. Ask the agent to run searcherries <command> --json and read the output, or connect the MCP server when your assistant supports MCP; both read the same data.

Privacy

The token reads the data of the Searcherries account that created it. The tool sends it only to app.searcherries.com, over HTTPS. Revoke the token on the MCP page if the computer is lost or the file is shared by mistake.