pp-dataforseo

<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/marketing/dataforseo/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". --> # DataForSEO — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `dataforseo-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer: ```bash npx -y @mvanhorn/printing-press install dataforseo --cli-only ``` 2. Verify: `dataforseo-pp-cli --version` 3. Ensure `$GOPATH/bin` (or `$HOME/go/bin`) is on `$PATH`. If the `npx` install fails before this CLI has a public-library category, install Node or use the category-specific Go fallback after publish. If `--version` reports "command not found" after install, the install step did not put the binary on `$PATH`. Do not proceed with skill commands until verification succeeds. A single-binary Go CLI over all 554 DataForSEO endpoints with offline SQLite-backed delta trackers, automatic Live↔Standard mode routing to dodge the 3.3× cost premium, and a pre-call cost estimator. Built to absorb everything the official MCP and the 6.4k-star claude-seo skill already do, then go further with rank tracking over a sitemap, AI-visibility deltas across ChatGPT/Claude/Gemini/Perplexity, and backlinks-since-last-run diffs. ## When to Use This CLI Reach for dataforseo-pp-cli whenever an SEO workflow touches DataForSEO endpoints — keyword volume hydration, SERP scraping, backlink audits, AI-search visibility tracking, on-page audits. Pick it over the official MCP when you want offline search over past results, automatic Live↔Standard cost routing, or a one-command Standard-mode poll loop. Pick it over the Python/TS clients when you want a single static binary on a server, a Cobra-style command tree, or `--dry-run` + `--cost-estimate` safety before billing. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Local state that compounds - **`keywords clean`** — Pre-clean keywords before sending to Google Ads volume so one bad keyword doesn't poison the whole batch, and surface task-level 40501 errors that DataForSEO hides behind a top-level 20000. _Reach for this when you'd otherwise call the Google Ads volume endpoint directly. DataForSEO returns top-level 20000 (success) even when every task inside failed validation; this command refuses to send poisoned batches and exits non-zero on hidden errors._ ```bash dataforseo-pp-cli keywords clean keywords.txt --json ``` - **`task bundle`** — Run the full Standard-mode lifecycle (task_post → tasks_ready poll → task_get → merge) as one command, with task IDs persisted to local SQLite so Ctrl-C or a laptop sleep doesn't lose the queue. _Use for any cost-sensitive batch job (which is most of them). One command replaces a Python poll-loop script and survives interruptions._ ```bash dataforseo-pp-cli task bundle serp/google/organic/task_post --in batch.json --json ``` - **`search`** — Every result-returning API call mirrors into local SQLite (keywords, serp_results, backlinks, ai_mentions) with FTS5 indexes; offline `search` runs FTS5 MATCH over snippets, URLs, anchor text, and AI-answer excerpts without re-billing. _Use whenever you're tempted to re-call the same SERP/volume/backlink endpoint. The local store makes re-queries free._ ```bash dataforseo-pp-cli search "tree service daytona" --json --select keyword,position,url ``` - **`keywords delta`** — Joins the current Google Ads volume API response against the last stored value per keyword in local SQLite and outputs movers sorted by absolute delta. _Reach for this whenever a content team asks 'which of the keywords we tracked last week moved.' DataForSEO doesn't return historical volume in one call; the local store enables this._ ```bash dataforseo-pp-cli keywords delta --since 7d --json --select keyword,volume,delta ``` - **`rank track`** — Parse a sitemap or URL→keyword map, call `serp/google/organic/live/advanced` per keyword, diff position + SERP features (AI Overview, featured snippet, knowledge panel, PAA) against last run, and flag movers and feature gains/losses. _Use weekly across any tracked page inventory. Replaces a manual GSC + incognito-Google ritual with one command._ ```bash dataforseo-pp-cli rank track --sitemap https://fsmstumpgrinding.com/sitemap.xml --features --json ``` - **`ai-visibility track`** — Call AI Optimization family endpoints (gemini, chat_gpt, llm_mentions, claude, perplexity) for a brand × keyword grid, store per-LLM mentions/excerpts in SQLite, and diff week-over-week presence + mention count per LLM. _Use weekly to track whether a brand's offer copy is being cited by ChatGPT/Claude/Gemini/Perplexity for buyer-intent queries. The mechanical alternative is asking each LLM by hand._ ```bash dataforseo-pp-cli ai-visibility track --brand "FSM Stump Grinding" --keywords keywords.txt --json ``` - **`backlinks new`** — Snapshot `backlinks/summary` + `referring_domains` + `anchors` into local SQLite; on each run diff against the prior snapshot and surface newly-acquired referring domains with anchor text. _Use weekly during any link-acquisition campaign (citation submissions, guest posts, PR placements) to confirm new backlinks landed and anchor text is on-brand._ ```bash dataforseo-pp-cli backlinks new --domain fsmstumpgrinding.com --json ``` ### Reachability mitigation - **`keywords volume`** — Auto-pick the cost-optimal execution mode based on batch size via `--mode auto`. Batches of 5 or fewer go through Live (sync, premium); larger batches route through Standard (queued, ~3.3× cheaper) with a managed poll loop. _Use whenever the batch size is uncertain. Pass `--mode auto` (the default) to avoid burning 3.3× the cost on a 200-keyword job because the user forgot to flip to Standard._ ```bash dataforseo-pp-cli keywords volume --keywords keywords.txt --mode auto --json ``` - **`cost estimate`** — Predict spend before any live API call using a static price table per endpoint family multiplied by the planned input size. Optional --confirm-over flag gates spending above a threshold. _Reach for this before any batch-size or backlink call. Joey's #1 fear with DataForSEO is accidentally burning the $50 deposit on one careless command; this prevents that._ ```bash dataforseo-pp-cli cost estimate keywords_data/google_ads/search_volume/live --keywords keywords.txt --confirm-over 1.00 ``` ## Anti-triggers — when NOT to use dataforseo-pp-cli - "Generate a PDF SEO audit for a client" — this CLI is data, not deliverables. Pipe its JSON into a separate report generator. - "Send the SEO digest to Telegram/Slack" — no notification delivery built in. Pipe to an existing alert bot manually. - "Write SEO content / blog drafts for me" — content generation lives elsewhere (the seo-audit, ai-seo, copywriting skills). This CLI surfaces data those skills consume. - "Run a general SEO audit on my site" — use the seo-audit-diy skill or seo-audit skill for per-page audits. This CLI exposes DataForSEO endpoints; the audit skills know how to compose them. - "Track competitor SERPs week-over-week with cross-domain overlap" — that feature was cut at the absorb gate (no documented weekly usage). Use `rank track` per-site instead. ## Command Reference **ai-optimization** — Manage ai optimization - `dataforseo-pp-cli ai-optimization ai-keyword-data-available-filters` — Here you will find all the necessary information about filters that can be used with AI Keyword Data API endpoints.... - `dataforseo-pp-cli ai-optimization ai-keyword-data-keywords-search-volume-live` — This endpoint provides search volume data for your target keywords, reflecting their estimated usage in AI tools.... - `dataforseo-pp-cli ai-optimization ai-keyword-data-locations-and-languages` — Using this endpoint you can get the full list of locations and languages supported in AI Keyword Data API. for more... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-responses-live` — Live ChatGPT LLM Responses endpoint allows you to retrieve structured responses from a specific ChatGPT AI model,... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-responses-models` — You will receive the list of available Chat GPT AI models by calling this API.   As a response of the API server,... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-responses-task-get` — Chat GPT LLM Responses endpoint allows you to retrieve structured responses from a specific Chat GPT model, based on... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-responses-task-post` — ChatGPT LLM Responses endpoint allows you to retrieve structured responses from a specific ChatGPT model, based on... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-responses-tasks-ready` — This endpoint is designed to provide you with a list of completed tasks, which haven’t been collected yet. If you... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-languages` — You will receive the list of languages by calling this API. for more info please visit... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-live-advanced` — Live ChatGPT LLM Scraper endpoint provides results from ChatGPT searches. The results are specific to the selected... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-live-html` — Live ChatGPT LLM Scraper API HTML provides a raw HTML page of the results for the specified keyword, language, and... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-locations` — You will receive the list of locations by this API call. You can filter the list of locations by country when... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-locations-country` — You will receive the list of locations by this API call. You can filter the list of locations by country when... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-task-get-advanced` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-task-post` — ChatGPT LLM Scraper API provides results from ChatGPT searches. The results are specific to the selected location... - `dataforseo-pp-cli ai-optimization chat-gpt-llm-scraper-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with the list of completed tasks, which haven’t been... - `dataforseo-pp-cli ai-optimization claude-llm-responses-live` — Live Claude LLM Responses endpoint allows you to retrieve structured responses from a specific Claude model, based... - `dataforseo-pp-cli ai-optimization claude-llm-responses-models` — You will receive the list of available Claude AI models by calling this API.   As a response of the API server, you... - `dataforseo-pp-cli ai-optimization claude-llm-responses-task-get` — Claude LLM Responses endpoint allows you to retrieve structured responses from a specific Claude model, based on the... - `dataforseo-pp-cli ai-optimization claude-llm-responses-task-post` — Claude LLM Responses endpoint allows you to retrieve structured responses from a specific Claude model, based on the... - `dataforseo-pp-cli ai-optimization claude-llm-responses-tasks-ready` — This endpoint is designed to provide you with a list of completed tasks, which haven’t been collected yet. If you... - `dataforseo-pp-cli ai-optimization gemini-llm-responses-live` — Live Gemini LLM Responses endpoint allows you to retrieve structured responses from a specific Gemini AI model,... - `dataforseo-pp-cli ai-optimization gemini-llm-responses-models` — You will receive the list of available Gemini AI models by calling this API.   As a response of the API server, you... - `dataforseo-pp-cli ai-optimization gemini-llm-responses-task-get` — Gemini LLM Responses endpoint allows you to retrieve structured responses from a specific Gemini model, based on the... - `dataforseo-pp-cli ai-optimization gemini-llm-responses-task-post` — Gemini LLM Responses endpoint allows you to retrieve structured responses from a specific Gemini model, based on the... - `dataforseo-pp-cli ai-optimization gemini-llm-responses-tasks-ready` — This endpoint is designed to provide you with a list of completed tasks, which haven’t been collected yet. If you... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-languages` — You will receive the list of languages by calling this API. for more info please visit... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-live-advanced` — Live Gemini LLM Scraper endpoint provides structured results from Gemini. The results are specific to the selected... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-live-html` — Live Gemini LLM Scraper API HTML provides a raw HTML page of the results for the specified keyword, language (see... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-locations` — You will receive the list of locations by this API call. You can filter the list of locations by country when... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-task-get-advanced` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-task-post` — Gemini LLM Scraper API provides structured results from Gemini. The results are specific to the selected location... - `dataforseo-pp-cli ai-optimization gemini-llm-scraper-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with the list of completed tasks, which haven’t been... - `dataforseo-pp-cli ai-optimization llm-mentions-aggregated-metrics-live` — Live LLM Mentions endpoint provides aggregated metrics for mentions of the keywords or domains specified in the... - `dataforseo-pp-cli ai-optimization llm-mentions-available-filters` — Here you will find all the necessary information about filters that can be used with AI Optimization LLM Mentions... - `dataforseo-pp-cli ai-optimization llm-mentions-cross-aggregated-metrics-live` — Live LLM Mentions endpoint provides aggregated metrics grouped by custom keys for mentions of the keywords or... - `dataforseo-pp-cli ai-optimization llm-mentions-locations-and-languages` — Using this endpoint you can get the full list of locations and languages supported in AI Optimization LLM Mentions... - `dataforseo-pp-cli ai-optimization llm-mentions-search-live` — Live LLM Mentions Search endpoint provides mention data and related metrics from AI searches. The results are... - `dataforseo-pp-cli ai-optimization llm-mentions-top-domains-live` — Live LLM Mentions Top Domains endpoint provides aggregated LLM mentions metrics grouped by the most frequently... - `dataforseo-pp-cli ai-optimization llm-mentions-top-pages-live` — Live LLM Mentions Top Pages endpoint provides aggregated LLM mentions metrics grouped by the most frequently... - `dataforseo-pp-cli ai-optimization perplexity-llm-responses-live` — Live Perplexity LLM Responses endpoint allows you to retrieve structured responses from a specific Perplexity AI... - `dataforseo-pp-cli ai-optimization perplexity-llm-responses-models` — You will receive the list of available Perplexity AI models by calling this API.   As a response of the API server,... **app-data** — Manage app data - `dataforseo-pp-cli app-data apple-app-info-task-get-advanced` — This endpoint will provide you with information about the mobile application specified in a POST request. You will... - `dataforseo-pp-cli app-data apple-app-info-task-post` — This endpoint will provide you with information about the App Store application specified in the app_id field of the... - `dataforseo-pp-cli app-data apple-app-info-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data apple-app-list-task-get-advanced` — This endpoint will provide you with a list of applications published in the top app charts on the App Store... - `dataforseo-pp-cli app-data apple-app-list-task-post` — This endpoint will provide you with a list of mobile applications published in the top app charts on the App Store... - `dataforseo-pp-cli app-data apple-app-list-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data apple-app-listings-categories` — This endpoint will provide you with a full list of app categories available on Apple App Store. for more info please... - `dataforseo-pp-cli app-data apple-app-listings-search-live` — This endpoint will provide you with a list of apps published on App Store along with additional information: its ID,... - `dataforseo-pp-cli app-data apple-app-reviews-task-get-advanced` — This endpoint will provide you with feedback data on applications listed on the App Store platform, including review... - `dataforseo-pp-cli app-data apple-app-reviews-task-post` — This endpoint will provide you with reviews published on the App Store platform for the app specified in the app_id... - `dataforseo-pp-cli app-data apple-app-reviews-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data apple-app-searches-task-get-advanced` — This endpoint will provide you with a list of apps ranking on the App Store for the keyword specified in a POST... - `dataforseo-pp-cli app-data apple-app-searches-task-post` — This endpoint will provide you with a list of apps ranking on the App Store for the specified keyword. The returned... - `dataforseo-pp-cli app-data apple-app-searches-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data apple-categories` — This endpoint will provide you with a full list of app categories available on App Store. for more info please visit... - `dataforseo-pp-cli app-data apple-languages` — By calling this endpoint you will receive the list of Apple languages supported in App Data API. for more info... - `dataforseo-pp-cli app-data apple-locations` — By calling this endpoint you will receive the list of Apple locations supported in App Data API. for more info... - `dataforseo-pp-cli app-data errors` — By calling this endpoint you will receive information about the App Data API tasks that returned an error within the... - `dataforseo-pp-cli app-data google-app-info-task-get-advanced` — This endpoint will provide you with information about the mobile application specified in a POST request. You will... - `dataforseo-pp-cli app-data google-app-info-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli app-data google-app-info-task-post` — This endpoint will provide you with information about the Google Play application specified in the app_id field of... - `dataforseo-pp-cli app-data google-app-info-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data google-app-list-task-get-advanced` — This endpoint will provide you with a list of applications published in the top charts on the Google Play platform,... - `dataforseo-pp-cli app-data google-app-list-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli app-data google-app-list-task-post` — This endpoint will provide you with a list of mobile applications published in the top charts on the Google Play... - `dataforseo-pp-cli app-data google-app-list-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data google-app-listings-categories` — This endpoint will provide you with a full list of app categories available on Google Play. for more info please... - `dataforseo-pp-cli app-data google-app-listings-search-live` — This endpoint will provide you with a list of apps published on Google Play along with additional information: its... - `dataforseo-pp-cli app-data google-app-reviews-task-get-advanced` — This endpoint will provide you with feedback data on applications listed on the Google Play platform, including... - `dataforseo-pp-cli app-data google-app-reviews-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli app-data google-app-reviews-task-post` — This endpoint will provide you with reviews published on the Google Play platform for the app specified in the... - `dataforseo-pp-cli app-data google-app-reviews-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data google-app-searches-task-get-advanced` — This endpoint will provide you with a list of apps ranking on Google Play for the keyword specified in a POST... - `dataforseo-pp-cli app-data google-app-searches-task-get-html` — Description of the fields for sending a request: for more info please visit... - `dataforseo-pp-cli app-data google-app-searches-task-post` — This endpoint will provide you with a list of apps ranking on Google Play for the specified keyword. The returned... - `dataforseo-pp-cli app-data google-app-searches-tasks-ready` — The ‘Tasks Ready’ endpoint is designed to provide you with a list of completed tasks that haven’t been... - `dataforseo-pp-cli app-data google-categories` — This endpoint will provide you with a full list of app categories available on Google Play. for more info please... - `dataforseo-pp-cli app-data google-languages` — By calling this endpoint you will receive the list of Google languages supported in App Data API. for more info... - `dataforseo-pp-cli app-data google-locations` — By calling this endpoint you will receive the list of Google locations supported in App Data API. for more info... - `dataforseo-pp-cli app-data google-locations-country` — By calling this endpoint you will receive the list of Google locations supported in App Data API. for more info... - `dataforseo-pp-cli app-data id-list` — This endpoint is designed to provide you with a list of IDs and metadata for all App Data tasks created within the...