Command reference — SEOCTL Docs

SEOCTL has fourteen workflow command families — volume, ideas, related, serp, rank, domain, links, backlinks, crawl, robots, sitemap, interlinks, url, and audit. Each one is atomic, returns a predictable JSON shape, and accepts a shared set of flags where they make sense. There are also four utility commands — auth, status, version, and instructions — covered in Install & authenticate and Agent setup.

Shared flags

Flag	Purpose
`--country us`	Two-letter country code. Defaults to `us`.
`--location-code 2840`	Override the location directly.
`--language en`	Set the language code.
`--limit 10`	Cap the number of rows in a list.
`--fields a,b,c`	Keep named fields; requested fields that are unavailable are returned as `null`.
`--bulk file`	Read inputs from a file (or `-` for stdin). See Bulk lookups.
`--pretty`	Pretty-print JSON for debugging.
`--timeout 30s`	Set the request timeout.

Hosted credit guide

volume: 1 credit per 10 keywords.
volume --global: 15 credits per request.
serp: 2 credits per 10 requested results.
ideas / related: 2 credits per 25 requested keywords.
rank: 2 credits per 50 checked SERP positions; default --depth 100 costs 4.
domain keywords / best-keywords / competitors: starts at 5 credits.
domain overlap / domain overlap --gap: starts at 8 credits.
backlinks / backlinks domains / backlinks broken / backlinks anchors: starts at 3 credits and requires a DataForSEO backlinks subscription.
links, crawl broken, crawl graph, crawl orphans, crawl opportunities, robots, sitemap, interlinks candidates, url status, audit page, and audit site: local; no SEOCTL API credits.

volume

Clickstream search volume for a keyword. Country volume returns keyword, volume, and source. Global volume returns total worldwide volume, scope: "global", source, and a compact top_countries distribution. A keyword with no data returns {keyword, found: false}.

seoctl volume "agent seo tools" --country us
seoctl volume "ahrefs vs semrush" --global
seoctl volume --bulk keywords.txt --country us
seoctl volume --bulk keywords.txt --global --fields keyword,volume,scope,top_countries

Volume-specific flags:

--global — use global clickstream volume instead of a country scope.
--top-countries 10 — set how many country rows to include with --global, up to 50.
--monthly — include the trailing 12-month search history.
--repair-missing — recheck null bulk rows as exact single-keyword lookups. On by default; each repaired row is an extra metered call.

--global is a separate scope. Do not combine it with --country, --location-code, --language, or --monthly.

ideas

Broad keyword expansion from a seed term — the widest net for discovery. Streams one JSON line per idea.

seoctl ideas "seo api" --country us --limit 25 --fields keyword,volume,cpc,difficulty,intent

Use ideas when broad ideation is useful. Add --closely-variants and --ignore-synonyms when you want phrase-style/provider-tightened ideas, but treat results as provider suggestions that can still be broad. Use related when precision matters.

SERP-related query expansion — the searches Google itself ties to your seed. Streams one line per query.

seoctl related "keyword research" --country us --limit 25

Use related before ideas when you want tighter, SERP-adjacent expansion.

Related-specific flag:

--depth 1 — set the related-search depth. If omitted, depth is chosen from --limit.

serp

Live top results for a query, with positions, result types, titles, URLs, and domains. Organic results are returned by default.

seoctl serp "best crm software" --country us --limit 10 --fields position,title,url,domain
seoctl serp "best crm software" --country us --limit 10 --all --fields position,type,title,url,domain

Use serp whenever the current ranked pages, titles, or domains matter. Use --all when the user wants the first real SERP items across organic, paid, and SERP features. Organic mode can return fewer rows than --limit when paid or SERP-feature items occupy the checked depth; output includes shortfall_reason when this happens.

rank

Where one domain sits for one keyword. Returns one object: domain, keyword, found, checked_depth, the best match’s position, rank_group, and rank_absolute, its url and title, plus a matches array of every position the domain holds. When the domain is not in range, found is false, rank fields are null, and not_found_reason is not_found_within_checked_depth.

seoctl rank stripe.com "payment processing software" --country us --depth 100
seoctl rank seoctl.com "best seo api" --country us --depth 20 --fields keyword,domain,found,checked_depth,position,url,not_found_reason

Rank-specific flag:

--depth 100 — how many SERP positions to scan, up to 200. Default is 100.
Hosted SEOCTL credit estimate: depth 1-50 costs 2 credits, 51-100 costs 4, 101-150 costs 6, and 151-200 costs 8.
Use --depth 10, --depth 20, or --depth 50 for cheaper top-N checks.
found:false means not found within the checked depth, not necessarily absent from Google.

domain

Competitor and domain research, organized into four subcommands. Each streams one line per result.

seoctl domain keywords stripe.com --country us --limit 25
seoctl domain best-keywords stripe.com --country us --intent commercial,transactional --limit 25
seoctl domain competitors stripe.com --country us --exclude-broad --limit 15
seoctl domain overlap stripe.com paddle.com --country us --limit 50
seoctl domain overlap stripe.com paddle.com --gap --country us --limit 50

domain keywords — ranking keywords ordered by current rank.
domain best-keywords — high-volume keywords a domain already ranks for.
domain competitors — domains with overlapping organic rankings.
domain overlap — keywords two domains both rank for.
domain overlap --gap — keywords the first domain ranks for and the second does not.

Domain-specific filters:

--intent commercial,transactional — keep keyword results with business or buying intent.
--min-volume 100 — keep keyword results above a monthly search-volume floor.
--exclude-broad — suppress broad UGC/social/wiki/video domains such as Reddit, YouTube, and Wikipedia from competitor results.
--exclude-domains reddit.com,youtube.com — suppress specific competitor domains.

Domain commands use DataForSEO Labs domain-index data. Validate important opportunities with live serp or rank checks because domain-index data and live SERP snapshots can differ.

links

Extract links from one page. links outbound returns third-party links. links internal returns same-site links. Add --broken to check each returned URL and include status_code, final_url, broken, and state. Link outputs include items_count, items_total, checked_count, broken_count, blocked_count, and state_counts.

seoctl links outbound https://example.com/page --limit 25 --fields url,host,text
seoctl links outbound https://example.com/page --broken --limit 25 --fields url,status_code,broken,state
seoctl links internal https://example.com/page --broken --limit 25 --path-exclude /login,/privacy

Links-specific flags:

--broken — check each returned URL.
--limit 25 — cap raw page-link output after filtering.
--path-contains /blog — only include links whose URL path contains a substring.
--path-exclude /login,/privacy — exclude links whose URL path contains any listed substring.
--same-host — treat only the exact host as internal. By default, subdomains on the same registrable domain are internal.
--concurrency 8 — set concurrent link status checks.

backlinks

Provider-index backlinks pointing to a page URL, domain, or subdomain. This uses DataForSEO’s backlink index; do not read the result as literally every link on the web. Use a full http(s) URL for a specific webpage target, or a bare domain/subdomain for a domain target.

seoctl backlinks https://example.com/page --limit 100 --fields source_url,anchor,target_url,last_seen,dofollow
seoctl backlinks example.com --domains --limit 25 --fields referring_domain,backlinks_count,sample_source_url,sample_anchor
seoctl backlinks https://example.com/page --lost --limit 25 --fields source_domain,source_url,anchor,target_url,last_seen
seoctl backlinks https://example.com/page --broken --limit 25 --fields source_domain,source_url,anchor,target_url,target_status_code
seoctl backlinks https://example.com/page --one-per-domain --status live
seoctl backlinks domains https://example.com/page --limit 25 --fields referring_domain,backlinks_count,sample_source_url,sample_anchor
seoctl backlinks broken example.com --limit 25 --fields target_url,target_status_code,source_url,anchor,last_seen
seoctl backlinks anchors example.com --limit 25 --fields anchor,backlinks,referring_domains,rank

Backlinks-specific flags:

backlinks TARGET — individual provider-index backlink rows for a page URL, domain, or subdomain.
backlinks TARGET --domains — one sample backlink per referring domain without switching subcommands.
backlinks domains TARGET — one sample backlink per referring domain for a URL, domain, or subdomain.
backlinks broken TARGET — backlinks pointing to target pages that return 4xx or 5xx.
backlinks anchors TARGET — aggregate anchor text rows.
--status live|lost|all — choose backlink status scope.
--lost — shortcut for --status lost.
--all — shortcut for --status all.
--broken — on the base backlinks command, return only provider rows marked as pointing to broken target URLs.
--one-per-domain — return one backlink per referring domain.
--one-per-anchor — return one backlink per anchor.
--include-indirect — include links through redirects or canonicals.
--include-internal — include same-domain/subdomain backlinks from the provider.
--dofollow-only — filter the returned result window to dofollow links.
--offset and --search-after-token — page through provider results.

Output includes target_scope, source_note, cost_note, backlink_status for the live/lost/all scope, and provider_mode for DataForSEO grouping mode (as_is, one_per_domain, or one_per_anchor). With --fields, search_after_token is hidden unless you request search_after_token or cursor. With backlinks broken --fields, rich broken_pages groups are hidden unless you request broken_pages; broken_pages_count remains as metadata.

When output has data.items, --fields trims item rows and keeps top-level metadata. Prefer row fields such as source_domain, referring_domain, target_url, and anchor when you want compact backlink output.

crawl

crawl broken starts from one entry URL, crawls internal pages, checks unique internal and outbound links once, and reports broken links with source-page provenance. crawl graph returns a bounded source-to-target link graph from the same kind of internal crawl. crawl orphans compares sitemap URLs against a bounded internal crawl and reports sitemap URLs not reached by internal links. crawl opportunities packages broken links, sitemap orphan candidates, and low-linked pages into one local crawl summary. All four are local and do not use SEOCTL API credits.

seoctl crawl broken https://example.com --max-pages 50 --max-links 500 --fields url,status_code,link_type,sources
seoctl crawl broken https://example.com --max-pages 25 --max-links 200 --outbound-only --include-pages --fields url,status_code,sources
seoctl crawl broken https://example.com --max-pages 10 --max-links 100 --all --internal-only --fields url,state,status_code,source_count
seoctl crawl graph https://example.com --max-pages 50 --max-links 500 --fields source_url,target_url,anchor,source_depth,target_depth
seoctl crawl graph https://example.com --max-pages 25 --include-outbound --fields source_url,target_url,link_type,anchor
seoctl crawl orphans https://example.com --max-pages 100 --max-sitemap-urls 1000 --limit 50 --fields url,sitemap_url,reason
seoctl crawl opportunities https://example.com --max-pages 50 --max-links 1000 --limit 50 --fields opportunity_type,url,priority,reason,source_count,sources

Crawl-specific flags:

--max-pages 50 — cap internal pages fetched.
--max-links 5000 — cap unique links checked by crawl broken or graph edges returned by crawl graph.
--max-links is the row-count safety valve for crawls. --fields trims fields, not row count.
--same-host — crawl only the exact host.
--concurrency 8 — set concurrent link status checks for crawl broken.
--all — include healthy and blocked links, not only broken links.
--internal-only — return only internal links in the broken/all inventory.
--outbound-only — return only outbound third-party links in the broken/all inventory.
--include-outbound — include third-party edges in crawl graph. By default, graph output is internal edges only.
--include-pages — include crawled page URLs and fetch status for audit provenance.
--source-limit 10 — cap source page URLs shown per link. source_count still reports the full count.
--max-sitemaps 20 — cap sitemap files fetched by crawl orphans.
--max-sitemap-urls 1000 — cap sitemap page URLs parsed by crawl orphans.
--limit 100 — cap returned orphan rows while preserving orphan_count.
--low-link-threshold 1 — for crawl opportunities, set how few distinct internal source pages qualifies a reached page as low-linked.

crawl broken output includes stop_reason, truncated, selected_unique_links, discovered_internal_count, discovered_outbound_count, discovered_link_type_counts, empty_reason, total_broken_count, broken_internal_count, broken_outbound_count, state_counts, link_type_counts, max_links_applies_to, and per-link source_count, min_source_depth, sources, and sources_truncated. When --outbound-only discovers no outbound links, empty_reason is no_outbound_links_discovered.

crawl graph output includes pages_crawled, edges_count, unique_targets_count, internal_edges_count, outbound_edges_count, pages, page_errors, stop_reason, and per-edge source_url, target_url, anchor, link_type, source_depth, target_depth, target_source_count, and target_sources.

crawl orphans output includes orphan_count, items_count, items_truncated, sitemap_urls_count, reached_sitemap_urls_count, reached_urls_count, crawl_stop_reason, sitemap summary context, and orphan rows with url, sitemap_url, and reason. Treat results as bounded crawl evidence when truncated:true or crawl_stop_reason is not complete.

crawl opportunities output includes opportunities_count, broken_links_count, orphan_pages_count, low_linked_pages_count, opportunity_counts, stop reasons for the underlying crawl phases, and combined rows with opportunity_type, priority, url, reason, and source provenance where applicable. Treat priority as a deterministic technical bucket, not semantic scoring.

robots

robots fetches and summarizes robots.txt for a domain or URL. It returns checked_url, user_agent_star_allowed, Sitemap directives, user-agent groups, allow/disallow counts, crawl delays, and warnings.

seoctl robots example.com --fields robots_url,checked_url,user_agent_star_allowed,found,sitemaps_count,disallow_count
seoctl robots https://example.com/private/page --pretty

Robots output is a practical crawler-rule summary. Common fields include groups, allows, disallows, status_code, and warnings. It is not a full search-engine crawler simulation.

sitemap

sitemap discovers XML sitemaps from robots.txt plus /sitemap.xml and returns sitemap-level summary facts. sitemap urls returns page URL rows with the sitemap file that supplied each URL.

seoctl sitemap example.com --fields sitemap_count,urls_count,discovered_sitemaps
seoctl sitemap urls example.com --max-urls 100 --fields url,sitemap_url

Sitemap-specific flags:

--max-sitemaps 20 — maximum sitemap files to fetch.
--max-urls 1000 — maximum sitemap page URLs to parse or return.
--source-limit 20 — maximum sitemap/page URL examples in summary output.

interlinks

interlinks candidates crawls internal pages from an entry URL, searches visible page text for supplied terms, and returns pages that mention those terms but do not already link to a target URL.

seoctl interlinks candidates https://example.com --target https://example.com/guide --terms "technical seo,site audit" --max-pages 50 --fields source_url,target_url,matched_terms,contexts,already_links_target
seoctl interlinks candidates https://example.com --target https://example.com/guide --terms-file terms.txt --max-pages 100

Interlinks-specific flags:

--target URL — target page that candidate pages should link to.
--terms "term one,term two" — comma-separated phrases to match in page text.
--terms-file terms.txt — one phrase per line.
--max-pages 50 — maximum internal pages to crawl.
By default, pages that already link to the target are counted but excluded from items.
--include-linked — include pages that already link to the target so existing anchors can be audited.
--context-chars 120 — snippet radius around each matched term.

The command returns deterministic matches and snippets. Semantic scoring, topic relevance, and prioritization belong to the agent or human using the output.

url

url status checks URLs locally without SEOCTL API credits. It returns HTTP status, final URL, redirect chain, content type, canonical URL, robots meta, X-Robots-Tag headers, and a basic indexability verdict.

seoctl url status https://example.com/page --fields url,status_code,final_url,canonical,indexable,indexability_reasons
seoctl url status --bulk urls.txt --fields url,status_code,final_url,indexable,indexability_reasons
printf '%s\n' https://example.com https://example.com/missing | seoctl url status --bulk - --limit 20

URL-status bulk emits JSONL in input order. It accepts one URL per line or the first CSV column, skips a url header, and keeps failed rows as ok:false envelopes.

audit

audit page checks one URL locally without SEOCTL API credits. It combines URL status and indexability basics with deterministic HTML facts: title, meta description, headings, word count, link counts, image alt basics, JSON-LD/schema type hints, hreflang, and social metadata counts.

seoctl audit page https://example.com/page --fields url,status_code,title,meta_description,h1_count,internal_links_count,outbound_links_count,indexable,word_count
seoctl audit page https://example.com/page --pretty
seoctl audit site https://example.com --max-pages 50 --max-sitemap-urls 1000 --fields url,status_code,title,meta_description,h1_count,indexable,images_missing_alt_count

Use audit page when you need facts for an on-page or technical SEO pass. It does not score quality, judge relevance, classify intent, or tell you whether metadata is “good”; that judgment belongs to the agent or human using the output.

Use audit site for a bounded sitewide facts pass. It returns robots/sitemap context, status/indexability buckets, duplicate title and description groups, missing/multiple H1 counts, image alt counts, schema/hreflang presence, per-page rows, and deterministic summary.issue_groups for common technical issues. Useful top-level summary paths include summary.indexability_counts, summary.non_200_count, summary.duplicate_title_count, summary.missing_meta_description_count, summary.pages_with_missing_alt_count, and summary.issue_groups.

Exact audit field names include image_count, schema_types, og_title, og_description, and twitter_card. Common aliases images_count and json_ld_types are also returned.

When to use which

volume --country — country-specific clickstream keyword demand.
volume --global — worldwide demand and top country distribution.
related — tighter SERP-adjacent query expansion.
ideas — broader expansion from a seed.
serp — current ranked pages and domains; add --all for paid and other SERP item types.
rank — one domain, one keyword.
domain — what a competitor ranks for, and where the gaps are.
links — internal/outbound links on one page.
backlinks — inbound links found in the provider index.
backlinks domains — referring-domain rows with one sample backlink per domain.
backlinks broken — broken backlink reclamation rows.
backlinks anchors — anchor text aggregation from the backlink index.
crawl broken — broken-link discovery across a small site crawl.
crawl graph — source-target-anchor internal link graph from a bounded crawl; add --include-outbound for third-party edges.
crawl orphans — sitemap URLs not reached by a bounded internal crawl.
crawl opportunities — combined local crawl facts for broken links, orphan candidates, and low-linked pages.
robots — robots.txt facts and Sitemap directives.
sitemap — XML sitemap discovery and URL rows.
interlinks candidates — internal pages that mention supplied terms but do not link to a target URL.
url status — HTTP status, redirects, canonical, and basic indexability for one URL or a bulk URL list.
audit page — deterministic on-page and technical facts for one URL.
audit site — deterministic sitewide technical facts from a bounded crawl, with robots/sitemap context and issue groups.

Run hundreds of lookups at once with Bulk lookups, or wire the whole surface into a coding agent with Agent setup.