Keyword research

semrush-cli provides commands for keyword discovery, intent analysis, local SERPs, competitor personalization, and batch exports using your Semrush web account.

Single keyword metricsCopy Anchor Link

Query volume, difficulty, intent, and trends for any search query:

semrush keyword-overview --keyword typescript --database us --json
semrush keyword-overview --keyword typescript --database us --device mobile --json
semrush keyword-serp --keyword typescript --database us --date 202609 --json
semrush keyword-ideas --keyword typescript --database us --currency EUR --json
semrush keyword-countries --keyword typescript --database us --json
semrush keyword-clusters --keyword typescript --database us --json

Key options for keyword queries:

• --database: Target country database code (default: us).
• --device: Search context, either desktop or mobile (default: desktop).
• --date: Historical snapshot in YYYYMM format (for example, 202609). Omit for current data.
• --currency: Three-letter currency code (default: USD).

Domain personalizationCopy Anchor Link

Personalize difficulty scores and intent metrics against an established website:

1. Identify the bare root domain:

   Copy Text

   semrush keyword-domain-root --domain www.example.com --json

2. Prepare the domain for personalization:

   Copy Text

   semrush keyword-domain-prepare --domain example.com --dry-run
   semrush keyword-domain-prepare --domain example.com --confirm --json

3. If preparation returns a pending job ID, inspect the status:

   Copy Text

   semrush keyword-domain-status --domain example.com --job-id 'job-id-placeholder' --json

4. Query metrics personalized to your prepared domain:

   Copy Text

   semrush keyword-overview --keyword typescript --domain example.com --json
   semrush keyword-clusters --keyword typescript --domain example.com --json

Keyword Magic ToolCopy Anchor Link

Perform in-depth exploratory keyword discovery with topic and word groupings:

semrush keyword-magic --keyword 'email marketing' --page 1 --page-size 50 --json
semrush keyword-magic --keyword 'email marketing' --questions-only --json
semrush keyword-magic-groups --keyword 'email marketing' --group-by topics --json
semrush keyword-magic-summary --keyword 'email marketing' --json

Use --group-by words to switch from topic grouping to classic word groups. Word groups can be ordered with --groups-sort-field volume or --groups-sort-field count.

AI search visibility and topicsCopy Anchor Link

Inspect search queries analyzed for AI visibility and large language model topic extraction:

semrush keyword-ai-databases --json
semrush keyword-ai-summary --keyword 'running shoes' --database us --json
semrush keyword-ai-topics --keyword 'running shoes' --database us --json

Local search analysisCopy Anchor Link

Retrieve search results and metrics for specific municipal locations:

semrush keyword-locations --input 'Chicago' --database us --json
semrush keyword-local-overview --keyword 'plumbing repair' --location-id 2840 --json
semrush keyword-local-serp --keyword 'plumbing repair' --location-id 2840 --limit 10 --json

Location IDs are positive integers obtained from keyword-locations. Local queries use current desktop data.

Bulk keyword analysisCopy Anchor Link

Analyze up to 100 keywords in a single call:

semrush keyword-bulk --keywords '["typescript","javascript","react"]' --database us --json

Export keyword reportsCopy Anchor Link

Export native CSV, semicolon-delimited CSV, or XLSX files directly to disk:

semrush keyword-bulk-export --keywords '["typescript","javascript"]' --output bulk.csv
semrush keyword-serp-export --keyword typescript --output serp.csv
semrush keyword-local-serp-export --keyword 'plumbing repair' --location-id 2840 --output local.csv

Export commands require the --output flag. The CLI checks the target path before initiating the export and refuses to overwrite existing files.

Download a Keyword Overview PDFCopy Anchor Link

semrush keyword-overview-pdf --keyword typescript --confirm --output overview.pdf

This creates an Essential report in My Reports, accepts its Privacy Policy and generates the native PDF. It uses reporting allowance. Email and scheduling are disabled. Add --ai-summary to include a summary using your account's AI summary allowance.

The CLI receipt includes data.manifest.report_id and data.manifest.task_id. MCP returns those IDs in data. The saved report stays in My Reports. Use reporting commands to inspect or delete it. If an export is interrupted after creation, inspect its task list before starting another export. Existing output files are not overwritten.

Refreshing keyword metricsCopy Anchor Link

Request fresh live metric updates from Semrush:

semrush keyword-refresh --keywords '["typescript"]' --database us --confirm --json
semrush keyword-refresh-status --keywords '["typescript"]' --database us --json

Refreshing consumes your account update quota.