SerpDetective CLI

Command-line tool for SEO keyword research via the SerpDetective API

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

Basic usage

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

# 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  [options]

Options:

• -c, --country — Country code (default: us)
• -f, --format — Output format: table, json, or csv (default: table)
• --api-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

# 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 (free, doesn't burn quota).

npx @serpdetective/cli suggestions  [options]

Options:

• -c, --country — Country code (default: us)
• -f, --format — Output format: table, json, or csv
• --google-only — Google suggestions only
• --bing-only — Bing suggestions only
• --api-key — Override API key for this call

Examples:

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

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

# 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. config — Config management

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

npx @serpdetective/cli config 

Subcommands:

• set — Set a config value
• get — 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 countries

us, uk, ca, au, in, de, fr, es, it, br, cn, jp, kr

Full list at the docs hub.

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
• 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

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

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