@mirage-cli/dataforseo-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Brufsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# dataforseo-cli
+
+`dfs` — an ergonomic CLI **and** a programmatic library for the DataForSEO API.
+
+- Curated commands cover ~30 high-value endpoints.
+- `dfs raw` escape hatch hits any of the 437 endpoints by path (driven off the official OpenAPI spec, slimmed at build time to a 327 KiB JSON index).
+- Same command definitions are exported as a library — the `command()` factory and `CommandSpec` / `Option` / `Operand` / `OperandKind` / `IOResult` shapes match `@struktoai/mirage-browser`, so a command authored here can be lifted into a mirage workspace later without rewrite.
+
+Bun + TypeScript. Companion Claude Code skill in `skill/`.
+
+## Install
+
+```bash
+bun install
+bun run build
+ln -sf "$PWD/dist/dfs.js" /usr/local/bin/dfs
+
+# Or compile a standalone binary:
+bun run compile && cp bin/dfs /usr/local/bin/dfs
+```
+
+## Auth
+
+```bash
+dfs login --login you@example.com --password <api_password>
+# or
+export DATAFORSEO_LOGIN=you@example.com
+export DATAFORSEO_PASSWORD=...
+```
+
+Credentials are written to `~/.config/dataforseo/config.json` (chmod 600).
+
+## Quick tour
+
+```bash
+dfs whoami
+dfs user
+
+# keyword research
+dfs keywords search-volume "seo tools" "keyword research" -o table
+dfs labs bulk-difficulty "seo tools" "ai search" "claude code"
+dfs labs intent "buy nike shoes" "how to tie shoelaces" -o table
+dfs keywords ranked example.com --limit 500 -o csv > ranked.csv
+
+# SERPs
+dfs serp google organic "best running shoes" --advanced --device mobile
+dfs serp google news "anthropic claude"
+dfs serp google images "minimalist desk"
+
+# backlinks + gap
+dfs backlinks summary example.com -o table
+dfs labs competitors example.com --limit 50
+dfs labs intersection example.com competitor.com --limit 200
+
+# AI visibility (LLM mentions, top-cited pages/domains, AI search volume)
+dfs ai top-domains "claude code" -o table
+dfs ai search-volume "seo tools" "keyword research"
+dfs ai ask "summarize the latest Claude release" --model claude
+
+# trends
+dfs trends explore "chatgpt" "claude" --date-from 2026-01-01
+```
+
+## Discovering endpoints
+
+```bash
+dfs endpoints tags
+dfs endpoints list --tag KeywordsData -q trends
+dfs endpoints show keywords_data/google_trends/explore/live
+```
+
+## Raw escape hatch
+
+```bash
+# Curated command doesn't exist? Hit the endpoint directly.
+dfs raw keywords_data/google_trends/explore/live \
+  -d '{"keywords":["seo","sem"],"location_code":2840}'
+
+# Key/value shorthand:
+dfs raw serp/google/organic/live/advanced \
+  --kv keyword="best laptops" location_code=2840 language_code=en device=mobile
+
+# Use the OpenAPI spec's example body:
+dfs raw serp/google/organic/live/regular --example
+```
+
+## Output
+
+Every data command supports `-o json|ndjson|table|csv|raw` and `--columns col1,col2`. Cost is printed to stderr.
+
+## Programmatic use
+
+The package exports three layers — pick whichever fits.
+
+**1. Plain async functions** — typed wrappers, return the raw `DfsResponse`:
+
+```ts
+import { keywordsSearchVolume } from 'dataforseo-cli'
+
+const resp = await keywordsSearchVolume({
+  keywords: ['seo tools', 'keyword research'],
+  locationName: 'United States',
+})
+```
+
+**2. Mirage-shaped command definitions** — call them via `invoke()` for CLI-style argument parsing without spawning a subprocess:
+
+```ts
+import { invoke, keywordsSearchVolumeCmd } from 'dataforseo-cli'
+
+const { text, result } = await invoke(keywordsSearchVolumeCmd, {
+  texts: ['seo tools'],
+  flags: { location: 'United States', output: 'table' },
+})
+console.log(text)
+console.log(`exit: ${result.exitCode}`)
+
+// Or pass argv tokens, like the CLI would receive:
+await invoke(keywordsSearchVolumeCmd, ['--location', 'United States', 'seo tools'])
+```
+
+**3. Author your own command using the same primitives** — same shape as `@struktoai/mirage-browser`:
+
+```ts
+import {
+  command,
+  CommandSpec,
+  IOResult,
+  Operand,
+  OperandKind,
+  Option,
+  invoke,
+} from 'dataforseo-cli'
+
+const greet = command({
+  name: 'greet',
+  spec: new CommandSpec({
+    description: 'Print hello <name>.',
+    options: [new Option({ short: 'u', long: 'upper', description: 'shout it' })],
+    positional: [new Operand({ kind: OperandKind.TEXT, name: 'name' })],
+  }),
+  async fn(parsed) {
+    const name = parsed.texts[0] ?? 'world'
+    const upper = parsed.flag('upper', false) === true
+    const msg = upper ? `HELLO ${name.toUpperCase()}!\n` : `hello ${name}\n`
+    return [new TextEncoder().encode(msg), new IOResult({ exitCode: 0 })]
+  },
+})
+
+await invoke(greet, { texts: ['alex'], flags: { upper: true } })
+```
+
+To plug your own commands into the CLI, import `toCommander(cmd)` and add the resulting `Command` to your commander program.
+
+## Refresh the spec
+
+When DataForSEO ships new endpoints:
+
+```bash
+bun run spec:refresh
+```
+
+Pulls the latest `openapi_specification.yaml` from `dataforseo/OpenApiDocumentation`.
+
+## Companion Claude skill
+
+Drop `skill/` into `~/.claude/skills/dataforseo` (or your skill manager) — it teaches Claude when to reach for `dfs` and how to use the curated commands + raw escape hatch.
+
+## License
+
+MIT

package/dist/api/ai.d.ts

@@ -0,0 +1,32 @@
+import { type DfsResponse } from "../lib/client.ts";
+import type { LocLang } from "./keywords.ts";
+export type AiModel = "chatgpt" | "claude" | "gemini" | "perplexity";
+/** AI-flavored search volume — how often a keyword is typed at AI tools. */
+export declare function aiSearchVolume(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Find LLM mentions matching one or more keyword targets. */
+export declare function aiMentions(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Top pages cited by AI for the given keyword targets. */
+export declare function aiTopPages(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Top domains cited by AI for the given keyword targets. */
+export declare function aiTopDomains(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Aggregated mention metrics (volume, sentiment, etc.) for keyword targets. */
+export declare function aiMentionMetrics(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Ask a specific LLM via DataForSEO's metered LLM proxy. */
+export declare function aiAsk(opts: {
+    model: AiModel;
+    message: string;
+    systemMessage?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+}): Promise<DfsResponse>;

package/dist/api/backlinks.d.ts

@@ -0,0 +1,20 @@
+import { type DfsResponse } from "../lib/client.ts";
+export declare function backlinksSummary(target: string): Promise<DfsResponse>;
+export declare function backlinksList(opts: {
+    target: string;
+    limit?: number;
+    mode?: "as_is" | "one_per_domain" | "one_per_anchor";
+}): Promise<DfsResponse>;
+export declare function backlinksReferringDomains(opts: {
+    target: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function backlinksAnchors(opts: {
+    target: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function backlinksCompetitors(opts: {
+    target: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function backlinksRanks(targets: string[]): Promise<DfsResponse>;

package/dist/api/keywords.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure async API functions for the "keywords" group. The CLI commands and
+ * any programmatic caller delegate to these.
+ */
+import { type DfsResponse } from "../lib/client.ts";
+export interface LocLang {
+    locationName?: string;
+    locationCode?: number;
+    languageName?: string;
+    languageCode?: string;
+}
+export declare function keywordsSearchVolume(opts: LocLang & {
+    keywords: string[];
+    includeSerpInfo?: boolean;
+}): Promise<DfsResponse>;
+export declare function keywordsIdeas(opts: LocLang & {
+    keywords: string[];
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function keywordsSuggestions(opts: LocLang & {
+    keyword: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function keywordsRanked(opts: LocLang & {
+    target: string;
+    limit?: number;
+}): Promise<DfsResponse>;

package/dist/api/labs.d.ts

@@ -0,0 +1,40 @@
+import { type DfsResponse } from "../lib/client.ts";
+import type { LocLang } from "./keywords.ts";
+export declare function labsCompetitors(opts: LocLang & {
+    target: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function labsIntersection(opts: LocLang & {
+    target1: string;
+    target2: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+export declare function labsOverview(opts: LocLang & {
+    target: string;
+}): Promise<DfsResponse>;
+export declare function labsRelated(opts: LocLang & {
+    keyword: string;
+    limit?: number;
+}): Promise<DfsResponse>;
+/** Full keyword overview: KD + volume + intent + SERP + backlink info in one call. */
+export declare function labsKeywordOverview(opts: LocLang & {
+    keywords: string[];
+    includeSerpInfo?: boolean;
+    includeClickstream?: boolean;
+}): Promise<DfsResponse>;
+/** Bulk keyword difficulty (KD) for up to 1000 keywords in one call. */
+export declare function labsBulkDifficulty(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Classify search intent (informational/navigational/commercial/transactional) for keywords. */
+export declare function labsIntent(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** Currently-trending top searches in a location. */
+export declare function labsTopSearches(opts: LocLang & {
+    limit?: number;
+}): Promise<DfsResponse>;
+/** Historical rank overview for a domain (month-by-month organic position counts). */
+export declare function labsHistorical(opts: LocLang & {
+    target: string;
+}): Promise<DfsResponse>;

package/dist/api/meta.d.ts

@@ -0,0 +1,4 @@
+import { type DfsResponse } from "../lib/client.ts";
+export declare function listLocations(api?: string): Promise<DfsResponse>;
+export declare function listLanguages(api?: string): Promise<DfsResponse>;
+export declare function userData(): Promise<DfsResponse>;

package/dist/api/serp.d.ts

@@ -0,0 +1,14 @@
+import { type DfsResponse } from "../lib/client.ts";
+import type { LocLang } from "./keywords.ts";
+export interface SerpOpts extends LocLang {
+    keyword: string;
+    device?: "desktop" | "mobile";
+    depth?: number;
+}
+export declare function serpGoogleOrganic(opts: SerpOpts & {
+    advanced?: boolean;
+}): Promise<DfsResponse>;
+export declare function serpGoogleMaps(opts: SerpOpts): Promise<DfsResponse>;
+export declare function serpYoutubeOrganic(opts: SerpOpts): Promise<DfsResponse>;
+export declare function serpGoogleNews(opts: SerpOpts): Promise<DfsResponse>;
+export declare function serpGoogleImages(opts: SerpOpts): Promise<DfsResponse>;

package/dist/api/trends.d.ts

@@ -0,0 +1,18 @@
+import { type DfsResponse } from "../lib/client.ts";
+import type { LocLang } from "./keywords.ts";
+export type TrendsType = "web" | "news" | "youtube" | "images" | "shopping";
+/** Google Trends "Explore" — popularity time series. */
+export declare function trendsExplore(opts: LocLang & {
+    keywords: string[];
+    type?: TrendsType;
+    dateFrom?: string;
+    dateTo?: string;
+}): Promise<DfsResponse>;
+/** DataForSEO Trends demography — age/gender breakdown for keywords. */
+export declare function trendsDemography(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;
+/** DataForSEO Trends sub-region interest — regional popularity heatmap. */
+export declare function trendsSubregion(opts: LocLang & {
+    keywords: string[];
+}): Promise<DfsResponse>;

package/dist/commands/ai.d.ts

@@ -0,0 +1,8 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const aiSearchVolumeCmd: CommandDef;
+export declare const aiMentionsCmd: CommandDef;
+export declare const aiTopPagesCmd: CommandDef;
+export declare const aiTopDomainsCmd: CommandDef;
+export declare const aiMetricsCmd: CommandDef;
+export declare const aiAskCmd: CommandDef;
+export declare const aiGroup: import("../index.ts").CommandGroup;

package/dist/commands/backlinks.d.ts

@@ -0,0 +1,8 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const backlinksSummaryCmd: CommandDef;
+export declare const backlinksListCmd: CommandDef;
+export declare const backlinksReferringDomainsCmd: CommandDef;
+export declare const backlinksAnchorsCmd: CommandDef;
+export declare const backlinksCompetitorsCmd: CommandDef;
+export declare const backlinksRanksCmd: CommandDef;
+export declare const backlinksGroup: import("../index.ts").CommandGroup;

package/dist/commands/endpoints.d.ts

@@ -0,0 +1,5 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const endpointsListCmd: CommandDef;
+export declare const endpointsShowCmd: CommandDef;
+export declare const endpointsTagsCmd: CommandDef;
+export declare const endpointsGroup: import("../index.ts").CommandGroup;

package/dist/commands/keywords.d.ts

@@ -0,0 +1,6 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const keywordsSearchVolumeCmd: CommandDef;
+export declare const keywordsIdeasCmd: CommandDef;
+export declare const keywordsSuggestionsCmd: CommandDef;
+export declare const keywordsRankedCmd: CommandDef;
+export declare const keywordsGroup: import("../index.ts").CommandGroup;

package/dist/commands/labs.d.ts

@@ -0,0 +1,11 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const labsCompetitorsCmd: CommandDef;
+export declare const labsIntersectionCmd: CommandDef;
+export declare const labsOverviewCmd: CommandDef;
+export declare const labsRelatedCmd: CommandDef;
+export declare const labsKeywordOverviewCmd: CommandDef;
+export declare const labsBulkDifficultyCmd: CommandDef;
+export declare const labsIntentCmd: CommandDef;
+export declare const labsTopSearchesCmd: CommandDef;
+export declare const labsHistoricalCmd: CommandDef;
+export declare const labsGroup: import("../index.ts").CommandGroup;

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const loginCmd: CommandDef;
+export declare const whoamiCmd: CommandDef;

package/dist/commands/meta.d.ts

@@ -0,0 +1,4 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const locationsCmd: CommandDef;
+export declare const languagesCmd: CommandDef;
+export declare const userCmd: CommandDef;

package/dist/commands/raw.d.ts

@@ -0,0 +1,2 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const rawCmd: CommandDef;

package/dist/commands/serp.d.ts

@@ -0,0 +1,7 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const serpGoogleOrganicCmd: CommandDef;
+export declare const serpGoogleMapsCmd: CommandDef;
+export declare const serpGoogleNewsCmd: CommandDef;
+export declare const serpGoogleImagesCmd: CommandDef;
+export declare const serpYoutubeOrganicCmd: CommandDef;
+export declare const serpGroup: import("../index.ts").CommandGroup;

package/dist/commands/trends.d.ts

@@ -0,0 +1,5 @@
+import { type CommandDef } from "../framework/index.ts";
+export declare const trendsExploreCmd: CommandDef;
+export declare const trendsDemographyCmd: CommandDef;
+export declare const trendsSubregionCmd: CommandDef;
+export declare const trendsGroup: import("../index.ts").CommandGroup;

package/dist/dfs.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * Build the dfs Commander program. Pure function — no side effects, safe to
+ * call from in-process wrappers (`@mirage-cli/dataforseo`) or from this file's
+ * own auto-parse block below when invoked as a CLI binary.
+ */
+export declare function buildProgram(): Command;