semrush-cli-setup

name	semrush-cli-setup
description	Install, configure, validate, and troubleshoot the semrush CLI. Use when the user needs Semrush API auth, SEMRUSH_API_KEY or SEMRUSH_OAUTH_TOKEN setup, output/cache/rate-limit configuration, shell completions, API balance checks, structured error handling, or a prerequisite check before running other Semrush CLI skills.

Semrush CLI Setup

Prepare the semrush CLI for agent-safe Semrush API work. Use this skill before domain, keyword, backlink, paid search, local SEO, traffic, or batch workflows when install state, credentials, output format, or API units are uncertain.

Baseline Checks

Run non-destructive checks first:

command -v semrush
semrush --version
semrush account auth status --output json --quiet
semrush account balance --output json --quiet
semrush cache stats --output json --quiet

If semrush is missing, install the semrush binary from the package source approved for the current project, then verify it is on PATH:

semrush --version

Use Rust 1.80+ when installing from source.

Authentication

Prefer environment variables for agent sessions:

export SEMRUSH_API_KEY="<set-locally>"
export SEMRUSH_OAUTH_TOKEN="<set-locally>"

Use SEMRUSH_API_KEY for v3 analytics endpoints: domain, keyword, backlink, trends, overview, account balance, and batch recipes. Use SEMRUSH_OAUTH_TOKEN for v4 endpoints: project and local SEO.

Use this precedence model when debugging auth:

1. --api-key flag
2. SEMRUSH_API_KEY environment variable
3. ~/.config/semrush/config.toml

Config file shape:

[auth]
api_key = "<set-locally>"

[defaults]
database = "us"
output = "json"
cache_ttl = 3600

[rate_limit]
requests_per_second = 10

[cache]
enabled = true

Agent Defaults

For machine parsing, force JSON and suppress non-data noise:

semrush domain overview example.com --database us --output json --quiet

Use --dry-run before broad, expensive, or unfamiliar calls:

semrush domain organic example.com --limit 1000 --dry-run --output json --quiet

Use cache intentionally:

semrush cache stats --output json --quiet
semrush domain overview example.com --cache-ttl 86400 --output json --quiet
semrush domain overview example.com --no-cache --output json --quiet
semrush cache clear

Global Options

Recognize and apply these options across workflows:

Option	Use
--database us	Regional database such as us, uk, de, or mobile-us.
--limit 100	Cap result count before parsing or exporting.
--offset 0	Page through large result sets.
--output json	Machine-readable output for analysis.
--output csv	Spreadsheet export.
--output jsonl	Streaming-friendly export for large lists.
--quiet	Suppress non-data messages.
--verbose	Debug unexpected behavior.
--dry-run	Estimate API unit cost without calling the API.

Error Handling

Treat CLI exit codes as actionable signals:

Exit	Meaning	Next action
0	Success	Parse stdout.
1	Auth error	Check API key, OAuth token, config precedence, and plan access.
2	Rate limit	Retry later or reduce batch size.
3	Input error	Fix command, required args, region, filters, or limits.
4	API/network error	Retry with --verbose; check Semrush status and network.

When a command fails, do not infer metrics. Report the failing command, stderr summary, exit code, and the smallest next diagnostic command.

Related Skills

• Use semrush-keyword-research for keyword expansion, difficulty, questions, and SERP ranking domains.
• Use semrush-competitor-research for organic domain and content gap work.
• Use semrush-backlink-audit for off-page and authority analysis.
• Use semrush-paid-search-intelligence for paid keyword, ad copy, and PLA research.
• Use semrush-traffic-trends for traffic source, geo, page, and trend analysis.
• Use semrush-local-seo for local listings and map-rank workflows.
• Use semrush-batch-workflows for reusable multi-step recipes.