Etsy niche research whose scores come with their evidence attached — seeded search, honest confidence, and a local store that turns repeat research into trends.
EverBee's data is the best Etsy research signal available, but its API will happily answer a question you did not ask: the default suggestion feeds return unranked filler regardless of your seed. This CLI queries the endpoints EverBee's own search boxes call, then stamps every returned row with a relevance score, an evidence count, and provenance. Confidence tracks evidence coverage, so a niche with no keyword support cannot come back looking confident. Use 'research niche' for a defensible verdict on one seed, 'research subniches' to rank a whole family of them, and 'selftest' to prove the data path is semantically sound before you trust a batch run.
Learn more at EverBee.
Created by @horknfbr (horknfbr).
Authentication
EverBee authenticates with a session token minted by Google SSO — there is no API-key page. Run 'everbee-pp-cli auth setup' for the steps to obtain a token, then store it with 'everbee-pp-cli auth set-token ', or set EVERBEE_ACCESS_TOKEN directly. Tokens expire; a 401 means the token needs replacing, not that the CLI is broken. Your EverBee plan gates research volume: the free Hobby plan allows only 10 keyword searches per month, and this CLI reports that cap as a typed error rather than as an empty result.
Quick Start
# Confirm config, token, and API reachability before spending any research quota.
everbee-pp-cli doctor --dry-run
# Prove the research path returns semantically relevant data, not just HTTP 200s.
everbee-pp-cli selftest --agent
# The core workflow: a scored niche verdict with its evidence and confidence attached.
everbee-pp-cli research niche "dad shirt" --agent
# Rank the child niches under a parent, with digital SVG/PNG listings excluded.
everbee-pp-cli research subniches --parent dad --product apparel --exclude-svg-png --agent
# Persist research locally so drift baselines and offline search have something to compare against.
everbee-pp-cli sync --resources products,keyword_research,shops
Unique Features
These capabilities aren't available in any other tool for this API.
Evidence-aware research
-
research niche — Score an Etsy niche from a seed keyword and get the evidence behind the score, not just the number.
Reach for this instead of a raw keyword call when you need to defend a low-competition claim: every verdict carries its evidence count, provenance, and an honest confidence.
everbee-pp-cli research niche "dad shirt" --agent
-
research subniches — Expand a parent niche into child niches and rank them on comparable, normalized scores.
Use this when the task is 'find me the least-crowded corner of X' rather than 'tell me about X'.
everbee-pp-cli research subniches --parent dad --product apparel --exclude-svg-png --agent
-
research competitors — Get the market shape of a niche: result count, median price, review and sales density, listing-age quartiles.
Answers 'who would I be competing against, and how entrenched are they' before any design work starts.
everbee-pp-cli research competitors "dad shirt" --agent
-
research tags — See which tags and title tokens the winning listings in a niche agree on, and whether demand is seasonal or evergreen when EverBee supplies trend data.
Use before writing a listing: it gives you the consensus vocabulary of the niche. The seasonality verdict is reported as 'unknown' when EverBee returns no trend data, which is common — it never guesses.
everbee-pp-cli research tags "dad shirt" --agent
Local state that compounds
-
research drift — Compare a niche against a saved baseline to see what actually moved since last time.
Turns repeated research into a trend instead of a series of disconnected screenshots.
everbee-pp-cli research drift "dad shirt" --agent
-
research listing — Resolve an Etsy listing URL or ID to what we actually know about it, and say so plainly when we know nothing.
Distinguishes 'this listing does not exist' from 'we have no data on it yet' — the two failures an agent must never conflate.
everbee-pp-cli research listing 4515173344 --agent
Agent-native plumbing
-
selftest — Check that the research path is not just reachable but actually returning relevant data.
Run this first in any automated session: it is the difference between 'the API answered' and 'the answer means something'.
everbee-pp-cli selftest --agent
Recipes
Defend a low-competition claim
everbee-pp-cli research niche "dad shirt" --agent
Returns demand, competition, saturation, price band, evidence count, and an opportunity score, plus the provenance of each metric so the verdict can be audited rather than trusted.
Find the least-crowded corner of a theme
everbee-pp-cli research subniches --parent dad --product apparel --exclude-svg-png --limit 20 --agent
Expands the parent into child niches from EverBee's own suggestion engine, drops nothing but flags product type, and normalizes scores so the children are actually comparable.
Narrow a verbose product payload for an agent
everbee-pp-cli products search --search-term "dad shirt" --agent --select results.title,results.price,results.listing_type,results.cached_est_mo_revenue
Product rows carry 68 fields each; --select trims the payload to the four that drive a decision, keeping agent context small.
Size up the competition before designing
everbee-pp-cli research competitors "dad shirt" --agent
Reports result count, median price, review and sales density, and listing-age quartiles, with the raw rows printed alongside so the statistics can be checked.
Track a niche week over week
everbee-pp-cli research drift "dad shirt" --save-baseline --agent
Saves a snapshot to the local store; re-running later diffs against it and reports what actually moved, with both fetch timestamps in provenance.
Usage
Run everbee-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
EVERBEE_CONFIG_DIR, EVERBEE_DATA_DIR, EVERBEE_STATE_DIR, or EVERBEE_CACHE_DIR
--home <dir> for this invocationEVERBEE_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export EVERBEE_HOME=/srv/everbee
everbee-pp-cli doctor
Under EVERBEE_HOME=/srv/everbee, the four dirs resolve to /srv/everbee/config, /srv/everbee/data, /srv/everbee/state, and /srv/everbee/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"everbee": {
"command": "everbee-pp-mcp",
"env": {
"EVERBEE_HOME": "/srv/everbee"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as EVERBEE_DATA_DIR overrides an explicit --home for that kind. Use EVERBEE_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting EVERBEE_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run everbee-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
account
EverBee account plan and research quota
everbee-pp-cli account - Show the EverBee account's current plan, research quota, and usage. Use this to check remaining keyword-search quota before a batch run — the free Hobby plan allows only 10 keyword searches per month.
keyword_research
Etsy keyword research — volume, competition, score, CPC, and trend
everbee-pp-cli keyword-research list - Browse EverBee's default keyword feed (what the UI shows before you search). This is a discovery/browse surface, NOT a search: it ignores any seed and returns EverBee's unranked default suggestions. To research a specific keyword use keyword-research search --keyword.everbee-pp-cli keyword-research search - Seeded keyword search. Returns keywords related to the seed with volume, competition, score, CPC, and trend, plus the seed's own demand-vs-competition metrics under searched_keyword. This is the endpoint the EverBee UI search box calls. Comma-join the keyword value to research multiple seeds at once.
products
Etsy product/listing research — sales, revenue, tags, price, listing type, and age
everbee-pp-cli products - Browse EverBee's default product feed (what the UI shows before you search). This is a discovery/browse surface, NOT a search: it ignores any search term. To research a specific product niche use products search --search-term.
shops
Etsy competitor shop research — revenue, sales, listing counts, conversion, and reviews
everbee-pp-cli shops resolve - Resolve an Etsy shop handle to its EverBee identity (shop_id, exact shop name, rating, review count, year created). Use this before any shop workflow so an unresolved handle is reported as unresolved rather than as a shop with zero research evidence.everbee-pp-cli shops search - Search EverBee's Etsy shop database. Pass a search term to find a specific competitor shop, or omit it to browse top shops by revenue.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
everbee-pp-cli recall <query> - Look up cached resources for a query before running discoveryeverbee-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)everbee-pp-cli learnings list - Inspect taught rowseverbee-pp-cli learnings forget <query> - Undo a teacheverbee-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejecteverbee-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countseverbee-pp-cli teach-pattern - Install a query/resource template up fronteverbee-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set EVERBEE_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of everbee-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
everbee-pp-cli keyword-research list
# JSON for scripting and agents
everbee-pp-cli keyword-research list --json
# Filter to specific fields
everbee-pp-cli keyword-research list --json --select results.title,results.price
# Dry run — show the request without sending
everbee-pp-cli keyword-research list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
everbee-pp-cli keyword-research list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set EVERBEE_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
everbee-pp-cli keyword-researcheverbee-pp-cli keyword-research listeverbee-pp-cli keyword-research searcheverbee-pp-cli productseverbee-pp-cli products searcheverbee-pp-cli products searcheverbee-pp-cli shopseverbee-pp-cli shops searcheverbee-pp-cli shops search
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Health Check
everbee-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run everbee-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/everbee-pp-cli/config.toml; --home, EVERBEE_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
EVERBEE_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, everbee-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
everbee-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $EVERBEE_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Every command returns 401 Could not authenticate with the provided credentials. — The EverBee session token expired. Re-capture it with 'everbee-pp-cli auth setup', or export a fresh EVERBEE_ACCESS_TOKEN.
- Keyword research returns a typed plan-cap error instead of results. — The free Hobby plan allows 10 keyword searches per month. Check remaining quota with 'everbee-pp-cli account --json'.
- Results look unrelated to the seed — mugs and posters for an apparel search. — You are reading a trending/browse feed, not a search. Use 'research niche' or 'products search --search-term', never the unranked browse feeds ('products' and 'keyword-research list'), to answer a query.
- A niche verdict reports confidence 0 and zero evidence. — That is an honest no-evidence result, not a failure. EverBee returned nothing relevant for that seed; widen the seed or lower --min-relevance to inspect the near-misses.
- research drift reports no baseline. — Save one first: 'everbee-pp-cli research drift "dad shirt" --save-baseline', then re-run later to see movement.