SerpDetective CLI

Command-line SEO research tool with API-backed metrics and direct-first search suggestions

Getting Started

Install

# Global install
npm install -g @serpdetective/cli

# Or skip the install with npx
npx @serpdetective/cli metrics "seo tools"

The examples below use npx @serpdetective/cli. If you installed globally, swap it with serpdetective.

Set your API key

1. Create an API key at SerpDetective Developers
2. Set the environment variable:

export SERPDETECTIVE_API_KEY=sk-your-api-key

Or use the config command:

npx @serpdetective/cli config set apiKey sk-your-api-key

metrics always requires an API key. suggestions tries direct Google/Bing requests first, and only needs an API key if it has to fall back to the SerpDetective API.

Basic usage

# Look up keyword metrics
npx @serpdetective/cli metrics "seo tools" "keyword research"

# Inspect locale support
npx @serpdetective/cli locales

# Get search suggestions
npx @serpdetective/cli suggestions "ai tools"

# Help
npx @serpdetective/cli --help

Commands

1. metrics — Keyword metrics

Get search volume, CPC, competition, and keyword difficulty.

npx @serpdetective/cli metrics <keywords...> [options]

Options:

• -c, --country <code> — Country code (default: us)
• --lang <code> — Language code for the selected market. Support is market-specific
• -f, --format <type> — Output format: table, json, or csv (default: table)
• --api-key <key> — Override API key for this call
• -v, --verbose — Show debug output
• --silent — Only emit data, no progress messages

Examples:

# Single keyword
npx @serpdetective/cli metrics "seo tools"

# Multiple keywords
npx @serpdetective/cli metrics "seo tools" "keyword research" "backlink checker"

# Pick a country
npx @serpdetective/cli metrics "seo tools" -c uk

# Multi-language market
npx @serpdetective/cli metrics "credit card" -c sg --lang en

# Inspect market support before querying
npx @serpdetective/cli locales il

# JSON (pipes well)
npx @serpdetective/cli metrics "seo tools" -f json | jq '.results[0].searchVolume'

# CSV (for Excel)
npx @serpdetective/cli metrics "seo" "marketing" -f csv > keywords.csv

Sample output:

✓ Fetching keyword metrics...

┌────────────────────┬────────────────┬───────┬─────────────┬────────────┐
│ Keyword            │ Search Volume  │ CPC   │ Competition │ Difficulty │
├────────────────────┼────────────────┼───────┼─────────────┼────────────┤
│ seo tools          │ 27,100         │ $8.56 │ 87          │ 76         │
│ keyword research   │ 18,100         │ $6.32 │ 82          │ 73         │
└────────────────────┴────────────────┴───────┴─────────────┴────────────┘

✓ Quota: 2 consumed, 98 remaining

2. suggestions — Search suggestions

Pull search suggestions from Google and Bing. The CLI tries direct provider requests first, then falls back to the SerpDetective API only for providers that fail directly.

npx @serpdetective/cli suggestions <keywords...> [options]

Options:

• -c, --country <code> — Country override for suggestions locale. Defaults to configured country, fallback us
• -l, --lang <code> — Language override for provider locale resolution, e.g. zh-cn, fr, es-419
• -f, --format <type> — Output format: table, json, or csv. Defaults to configured format, fallback table
• --google-only — Google suggestions only
• --bing-only — Bing suggestions only
• --api-key <key> — Override API key for API fallback requests
• -v, --verbose — Show debug output
• --silent — Only emit data, no progress messages

Behavior:

• Direct provider requests are attempted before any API call.
• API fallback is provider-scoped, so one provider can succeed directly while the other falls back.
• --country and --lang are combined into provider-specific locale parameters such as Google hl and Bing mkt / setlang.
• Google may return locale-specific encodings such as GB2312; the CLI decodes them before parsing.
• Suggestions can work without an API key if direct provider requests succeed.
• Use npx @serpdetective/cli locales --suggestions [country] [--lang <code>] to inspect resolved provider params before querying.

Examples:

# Search suggestions
npx @serpdetective/cli suggestions "ai tools"

# Google only
npx @serpdetective/cli suggestions "seo tools" --google-only

# French suggestions in Canada
npx @serpdetective/cli suggestions "seo" --country ca --lang fr

# US Spanish locale via Bing
npx @serpdetective/cli suggestions "seo" --bing-only --country us --lang es-419 -f json

# Inspect suggestions locale support
npx @serpdetective/cli locales --suggestions uk --lang fr

# As JSON
npx @serpdetective/cli suggestions "marketing" -f json

Sample output:

✓ Fetching search suggestions...

Suggestions for "ai tools":

Google:
  • ai tools for business
  • ai tools for writing
  • ai tools for design
  • ai tools free

Bing:
  • ai tools comparison
  • ai tools 2026

3. locales — Locale discovery

Inspect current locale support without making API requests.

npx @serpdetective/cli locales [country] [options]

Options:

• --suggestions — Show suggestions locale support instead of metrics markets
• --lang <code> — With --suggestions, resolve provider params for a specific language
• --languages — With --suggestions, print the full supported suggestions language list

Examples:

# Metrics market catalog
npx @serpdetective/cli locales

# Single metrics market
npx @serpdetective/cli locales cn

# Suggestions country catalog
npx @serpdetective/cli locales --suggestions

# Suggestions locale resolution for a single country + language
npx @serpdetective/cli locales --suggestions uk --lang fr

# Full suggestions language list
npx @serpdetective/cli locales --suggestions --languages

4. config — Config management

Manage CLI settings (stored in ~/.serpdetectiverc).

npx @serpdetective/cli config <command>

Subcommands:

• set <key> <value> — Set a config value
• get <key> — Read a config value
• list — Show everything
• reset — Wipe config

Examples:

# Store your API key
npx @serpdetective/cli config set apiKey sk-abc123...

# Read it back
npx @serpdetective/cli config get apiKey

# Set a default country
npx @serpdetective/cli config set defaultCountry uk

# Show all settings
npx @serpdetective/cli config list

# Start fresh
npx @serpdetective/cli config reset

Configuration

Three ways to configure the CLI (highest to lowest priority):

1. CLI flags

npx @serpdetective/cli metrics "seo" --api-key sk-abc123... -c uk

2. Environment variables

export SERPDETECTIVE_API_KEY=sk-abc123...
export SERPDETECTIVE_API_URL=https://app.serpdetective.com/api
export SERPDETECTIVE_DEFAULT_COUNTRY=us

The old env vars SERP_CONTEXT_API_KEY / SERP_CONTEXT_API_URL / SERP_CONTEXT_DEFAULT_COUNTRY still work, but you should migrate to the new names.

3. Config file

Drop a .serpdetectiverc file (JSON or YAML):

{
  "apiKey": "sk-abc123...",
  "defaultCountry": "us",
  "outputFormat": "table"
}

Or a serpdetective.config.js:

module.exports = {
  apiKey: process.env.SERPDETECTIVE_API_KEY,
  defaultCountry: 'us',
  outputFormat: 'table',
};

Old config files .serp-contextrc / serp-context.config.js still work, but you should migrate to the new names.

Supported locales

Locale support is intentionally discoverable from the CLI instead of hard-coded in this README, because:

• metrics follows the official Labs market-language matrix plus product aliases such as cn
• suggestions follows provider-specific Google/Bing locale mappings
• both lists evolve over time

Use these commands for the current source of truth:

# Metrics markets and languages
npx @serpdetective/cli locales
npx @serpdetective/cli locales <country>

# Suggestions countries, resolved params, and language list
npx @serpdetective/cli locales --suggestions
npx @serpdetective/cli locales --suggestions <country> --lang <code>
npx @serpdetective/cli locales --suggestions --languages

Scripting & automation

Shell

#!/bin/bash

# batch_analyze.sh — bulk keyword analysis

keywords="seo marketing analytics content"
npx @serpdetective/cli metrics $keywords -f csv > results.csv
echo "✓ Results saved to results.csv"

Node.js

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

async function getKeywordMetrics(keywords) {
  const keywordsStr = keywords.map(k => `"${k}"`).join(' ');
  const { stdout } = await execAsync(
    `npx @serpdetective/cli metrics ${keywordsStr} -f json`
  );
  return JSON.parse(stdout);
}

const data = await getKeywordMetrics(['seo tools', 'keyword research']);
console.log(data.results[0].searchVolume);

Python

import subprocess
import json

def get_keyword_metrics(keywords):
    result = subprocess.run(
        ['npx', '@serpdetective/cli', 'metrics'] + keywords + ['-f', 'json'],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

data = get_keyword_metrics(['seo tools', 'keyword research'])
print(data['results'][0]['searchVolume'])

Pipes

# Pluck a single value
npx @serpdetective/cli metrics "seo tools" -f json | jq '.results[0].searchVolume'

# Filter high-volume keywords (>10,000)
npx @serpdetective/cli metrics "seo" "marketing" "analytics" -f json \
  | jq '.results[] | select(.searchVolume > 10000)'

# Sort by volume, descending
npx @serpdetective/cli metrics "seo" "marketing" "content" -f json \
  | jq '.results | sort_by(.searchVolume) | reverse'

Output formats

Table (default)

┌────────────────────┬────────────────┬───────┬─────────────┬────────────┐
│ Keyword            │ Search Volume  │ CPC   │ Competition │ Difficulty │
├────────────────────┼────────────────┼───────┼─────────────┼────────────┤
│ seo tools          │ 27,100         │ $8.56 │ 87          │ 76         │
└────────────────────┴────────────────┴───────┴─────────────┴────────────┘

JSON

{
  "results": [
    {
      "keyword": "seo tools",
      "searchVolume": 27100,
      "cpc": 8.56,
      "competition": 87,
      "keywordDifficulty": 76
    }
  ],
  "meta": {
    "quotaConsumed": 1,
    "quotaRemaining": 99
  }
}

CSV

Keyword,Search Volume,CPC,Competition,Difficulty
seo tools,27100,8.56,87,76
keyword research,18100,6.32,82,73

Errors

The CLI handles common failures gracefully:

• Missing API key — prompts you to configure one for metrics, or when suggestions fallback is needed
• Invalid API key — tells you to double-check it
• Rate limited — shows a retry hint
• Quota exhausted — suggests upgrading your plan
• Network errors — auto-retries

Security

1. Don't hardcode your API key
2. Use env vars or the config file instead
3. Keep .serpdetectiverc out of git (add it to .gitignore)
4. Rotate keys periodically
5. Revoke keys you no longer use

Resources

• SerpDetective
• CLI docs
• Docs hub
• Developer console
• Plans & billing
• CLI technical design doc (historical design snapshot)

Troubleshooting

"API key not found"

# Check your env
echo $SERPDETECTIVE_API_KEY

# Check config
npx @serpdetective/cli config list

# Set it
npx @serpdetective/cli config set apiKey sk-your-api-key

If this happens on suggestions, direct provider access likely failed and the command needed API fallback.

Connection errors

# Turn on verbose logging
npx @serpdetective/cli metrics "seo" -v

# Check the API URL
npx @serpdetective/cli config get apiUrl

Quota issues

# See your quota in the meta field
npx @serpdetective/cli metrics "seo" -f json | jq '.meta'

Feedback

• Bugs: GitHub Issues
• Feature ideas: GitHub Discussions
• Email: [email protected]

License

MIT — See LICENSE