Keyword Tool data from eRank, plus local scoring, drift, and listing-gap analysis for Etsy sellers.
Use eRank from a terminal to capture keyword stats, top listings, tags, related searches, and keyword lists in agent-ready formats. The CLI adds opportunity scoring, drift detection, and listing-gap analysis on top of the captured Keyword Tool workflow.
Learn more at eRank.
Created by @horknfbr (horknfbr).
Authentication
This CLI uses an authenticated eRank member session. Run the generated auth setup flow before live commands; captured endpoints require the same browser-compatible session that powers eRank's member tools.
Quick Start
# Confirm eRank session setup and browser-compatible transport.
erank-pp-cli doctor
# Pull a compact top-listing view for one Etsy keyword.
erank-pp-cli keyword-tool list-top-listings --keyword "dad mug" --marketplace etsy --country USA --agent --select title,shop_name,price,tags
# Convert raw eRank keyword signals into a seller decision score.
erank-pp-cli opportunity "dad mug" --source etsy --country USA --agent
# Find recurring tags backed by several eRank surfaces.
erank-pp-cli tags consensus "dad mug" --source etsy --country USA --min-count 3 --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Seller decisions
-
opportunity — Score a keyword as a seller opportunity using eRank stats, difficulty, competition, and current top listings.
Use this when an agent needs a go/no-go read on a keyword instead of separate raw metric calls.
erank-pp-cli opportunity "dad mug" --source etsy --country USA --agent
-
lists optimize — Rank saved keyword lists by weak, saturated, overlapping, and missing keyword opportunities.
Use this when an agent needs to clean up a seller's research list before drafting listings.
erank-pp-cli lists optimize "Father's Day mugs" --country USA --agent
-
saturation — Flag crowded keywords by combining competition, difficulty, tag reuse, and top-listing density.
Use this to avoid chasing keywords that look popular but are too crowded to enter.
erank-pp-cli saturation "dad mug" --source etsy --country USA --agent
Listing optimization
-
listing gaps — Compare a draft listing title and tags against phrases and tags appearing in top eRank results.
Use this before publishing or rewriting an Etsy listing from keyword evidence.
erank-pp-cli listing gaps "dad mug" --title "Funny Dad Coffee Mug" --tags "dad gift,fathers day,mug" --agent
-
tags consensus — Find tags that repeatedly appear across top listings, Etsy tag data, related searches, and near matches.
Use this when an agent needs defensible tag candidates grounded in multiple signals.
erank-pp-cli tags consensus "dad mug" --source etsy --country USA --min-count 3 --agent
Local history
-
watch drift — Detect meaningful changes in keyword competition, difficulty, and top listings across saved snapshots.
Use this to monitor seasonal or competitive shifts without rereading full eRank pages.
erank-pp-cli watch drift "dad mug" --days 30 --threshold 15 --agent
Product research
-
angles — Extract product angles from related searches, near matches, tags, and current top listings.
Use this when an agent needs product-angle ideas tied to observed demand signals.
erank-pp-cli angles "dad mug" --source etsy --country USA --limit 10 --agent
Recipes
Compact top listings for an agent
erank-pp-cli keyword-tool list-top-listings --keyword "dad mug" --marketplace etsy --country USA --agent --select title,shop_name,price,tags
Returns only listing fields an agent needs for comparison.
Score a niche before drafting
erank-pp-cli opportunity "dad mug" --source etsy --country USA --agent
Combines eRank keyword and listing signals into a go/no-go score.
Find defensible tags
erank-pp-cli tags consensus "dad mug" --source etsy --country USA --min-count 3 --agent
Extracts recurring tag evidence across captured eRank surfaces.
Check draft listing gaps
erank-pp-cli listing gaps "dad mug" --title "Funny Dad Coffee Mug" --tags "dad gift,fathers day,mug" --agent
Compares draft copy to top-ranking listing evidence.
Usage
Run erank-pp-cli --help for the full command reference and flag list.
Commands
account
Operations on sideBarCollapse
erank-pp-cli account get-user-preferences - GET /api/account/user-preferences/{user_preference_id}erank-pp-cli account list-keyword-tool.near-matches.table.config.columns - GET /api/account/user-preferences/keyword-tool.near-matches.table.config.columnserank-pp-cli account list-kt-keyword-ideas - GET /api/account/user-preferences/kt_keyword_ideaserank-pp-cli account list-member-preferences - GET /api/account/member-preferenceserank-pp-cli account list-search-country - GET /api/account/user-preferences/searchCountryerank-pp-cli account list-side-bar-collapse - GET /api/account/user-preferences/sideBarCollapse
build
Operations on version.json
erank-pp-cli build - GET /build/version.json
check-paddle-restriction
Operations on check-paddle-restriction
erank-pp-cli check-paddle-restriction - GET /api/check-paddle-restriction
intercom
Operations on intercom
erank-pp-cli intercom - GET /api/intercom
keyword-tool
Operations on stats
erank-pp-cli keyword-tool create-competition - POST /api/keyword-tool/competitionerank-pp-cli keyword-tool create-google-data - POST /api/keyword-tool/google-dataerank-pp-cli keyword-tool create-keyword-difficulty - POST /api/keyword-tool/keyword-difficultyerank-pp-cli keyword-tool create-save-history - POST /api/keyword-tool/save-historyerank-pp-cli keyword-tool list-etsy-tags - GET /api/keyword-tool/etsy-tagserank-pp-cli keyword-tool list-near-matches - GET /api/keyword-tool/near-matcheserank-pp-cli keyword-tool list-related-searches - GET /api/keyword-tool/related-searcheserank-pp-cli keyword-tool list-stats - GET /api/keyword-tool/statserank-pp-cli keyword-tool list-top-listings - GET /api/keyword-tool/top-listings
keywordlist
Operations on names
erank-pp-cli keywordlist list-names - GET /api/keywordlist/nameserank-pp-cli keywordlist list-terms - GET /api/keywordlist/terms
member-shops
Operations on member-shops
erank-pp-cli member-shops - GET /api/member-shops
motd-v3
Operations on keyword-tool
erank-pp-cli motd-v3 - GET /api/motd-v3/keyword-tool
oauth
Operations on check-token-validity
erank-pp-cli oauth - GET /api/oauth/check-token-validity
quota
Operations on daily
erank-pp-cli quota - GET /api/quota/daily
refresh-data
Operations on last-refresh
erank-pp-cli refresh-data - GET /api/refresh-data/listings/last-refresh
Output Formats
# Human-readable table (default in terminal, JSON when piped)
erank-pp-cli account get-user-preferences mock-value
# JSON for scripting and agents
erank-pp-cli account get-user-preferences mock-value --json
# Filter to specific fields
erank-pp-cli account get-user-preferences mock-value --json --select id,name,status
# Dry run — show the request without sending
erank-pp-cli account get-user-preferences mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
erank-pp-cli account get-user-preferences mock-value --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
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- 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 ERANK_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
erank-pp-cli accounterank-pp-cli account geterank-pp-cli account listerank-pp-cli account searcherank-pp-cli account-user-preferences-keyword-tool-near-matches-table-config-columnserank-pp-cli account-user-preferences-keyword-tool-near-matches-table-config-columns geterank-pp-cli account-user-preferences-keyword-tool-near-matches-table-config-columns listerank-pp-cli account-user-preferences-keyword-tool-near-matches-table-config-columns searcherank-pp-cli account-user-preferences-kt-keyword-ideaserank-pp-cli account-user-preferences-kt-keyword-ideas geterank-pp-cli account-user-preferences-kt-keyword-ideas listerank-pp-cli account-user-preferences-kt-keyword-ideas searcherank-pp-cli account-user-preferences-search-countryerank-pp-cli account-user-preferences-search-country geterank-pp-cli account-user-preferences-search-country listerank-pp-cli account-user-preferences-search-country searcherank-pp-cli account-user-preferences-side-bar-collapseerank-pp-cli account-user-preferences-side-bar-collapse geterank-pp-cli account-user-preferences-side-bar-collapse listerank-pp-cli account-user-preferences-side-bar-collapse searcherank-pp-cli builderank-pp-cli build geterank-pp-cli build listerank-pp-cli build searcherank-pp-cli check-paddle-restrictionerank-pp-cli check-paddle-restriction geterank-pp-cli check-paddle-restriction listerank-pp-cli check-paddle-restriction searcherank-pp-cli intercomerank-pp-cli intercom geterank-pp-cli intercom listerank-pp-cli intercom searcherank-pp-cli keywordlisterank-pp-cli keywordlist geterank-pp-cli keywordlist listerank-pp-cli keywordlist searcherank-pp-cli keywordlist-termserank-pp-cli keywordlist-terms geterank-pp-cli keywordlist-terms listerank-pp-cli keywordlist-terms searcherank-pp-cli member-shopserank-pp-cli member-shops geterank-pp-cli member-shops listerank-pp-cli member-shops searcherank-pp-cli motd-v3erank-pp-cli motd-v3 geterank-pp-cli motd-v3 listerank-pp-cli motd-v3 searcherank-pp-cli oautherank-pp-cli oauth geterank-pp-cli oauth listerank-pp-cli oauth searcherank-pp-cli quotaerank-pp-cli quota geterank-pp-cli quota listerank-pp-cli quota searcherank-pp-cli refresh-dataerank-pp-cli refresh-data geterank-pp-cli refresh-data listerank-pp-cli refresh-data 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
erank-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/erank-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
ERANK_XSRF_TOKEN | harvested | Yes | Populated automatically by auth login. |
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, erank-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
erank-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $ERANK_XSRF_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Commands return login or empty member data. — Refresh the eRank browser session with the generated auth setup flow, then rerun
erank-pp-cli doctor.
- Keyword calls stop returning data. — Run
erank-pp-cli quota list-daily --agent and retry after quota resets if daily lookups are exhausted.
- POST keyword endpoints fail live verification. — Use
--dry-run first; this capture has weak POST schema confidence from a single keyword workflow.
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
Discovery Signals
This CLI was generated with browser-captured traffic analysis.
- Target observed: https://members.erank.com/keyword-tool/top-listings
- Capture coverage: 61 API entries from 233 total network entries
- Reachability: browser_http (78% confidence)
- Protocols: rest_json (75% confidence)
- Auth signals: api_key — query: keyword
- Protection signals: cloudflare (90% confidence)
- Generation hints: browser_http_transport, requires_protected_client, weak_schema_confidence
- Candidate command ideas: create_competition — Derived from observed POST /api/keyword-tool/competition traffic.; create_google_data — Derived from observed POST /api/keyword-tool/google-data traffic.; create_keyword_difficulty — Derived from observed POST /api/keyword-tool/keyword-difficulty traffic.; create_save_history — Derived from observed POST /api/keyword-tool/save-history traffic.; get_user_preferences — Derived from observed GET /api/account/user-preferences/{user_preference_id} traffic.; list_check_paddle_restriction — Derived from observed GET /api/check-paddle-restriction traffic.; list_check_token_validity — Derived from observed GET /api/oauth/check-token-validity traffic.; list_customer — Derived from observed GET /dotjs/v1/quests/customer/ traffic.
Warnings from discovery:
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
- empty_payload: API-looking request returned an empty or null payload; schema confidence is weak.
Generated by CLI Printing Press