Quickstart — SEOCTL Docs

This page assumes you have already installed and authenticated the CLI.

Every SEOCTL command writes compact JSON to standard output. Atomic commands return one envelope with ok, command, query, data, and meta. Bulk mode streams JSONL, one envelope per input row. Output is built to be read by a machine, not formatted into a table.

Your first lookup

Get real search demand for a keyword:

seoctl volume "agent seo tools" --country us

{"keyword":"agent seo tools","volume":2400,"cpc":3.1,"competition":"LOW","competition_index":34}

Inspect a live SERP

See who currently ranks for a query:

seoctl serp "best seo api" --country us --limit 5

SERP results live under data.items with position, title, URL, and domain.

By default, serp returns organic results. If you need the first real SERP items across paid, organic, and SERP features, add --all:

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

Check links

Inspect links on one page, or add status checks when broken links matter:

seoctl links outbound https://example.com/page --broken --fields url,status_code,broken,state
seoctl links internal https://example.com/page --fields url,text

For a small site-wide pass, crawl internal pages from one entry URL and report unique broken links:

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 20 --max-links 200 --include-pages

Map internal links as source-target-anchor edges:

seoctl crawl graph https://example.com --max-pages 50 --max-links 500 --fields source_url,target_url,anchor,source_depth,target_depth

Compare sitemap URLs against a bounded crawl to find orphan candidates:

seoctl crawl orphans https://example.com --max-pages 100 --max-sitemap-urls 1000 --limit 50 --fields url,sitemap_url,reason

Package broken links, orphan candidates, and low-linked pages into one deterministic local crawl summary:

seoctl crawl opportunities https://example.com --max-pages 50 --max-links 1000 --limit 50 --fields opportunity_type,url,priority,reason,source_count

Check robots.txt, sitemap discovery, and sitemap URL rows:

seoctl robots example.com --fields robots_url,checked_url,user_agent_star_allowed,found,sitemaps_count,disallow_count
seoctl sitemap example.com --fields sitemap_count,urls_count,discovered_sitemaps
seoctl sitemap urls example.com --max-urls 100 --fields url,sitemap_url

Find deterministic internal-linking candidates for a target page:

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,already_links_target

Check one URL’s status, redirect target, canonical, and indexability basics:

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

Run a one-page audit for deterministic on-page facts:

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 site https://example.com --max-pages 50 --max-sitemap-urls 1000 --fields url,status_code,title,h1_count,indexable,images_missing_alt_count

Audit fields use exact names such as image_count, schema_types, og_title, og_description, and twitter_card. Site audits also include deterministic summary.issue_groups for common technical issues.

Check a rank

Find where a domain sits for a single keyword:

seoctl rank ahrefs.com "seo api" --country us

{"domain":"ahrefs.com","keyword":"seo api","found":true,"checked_depth":100,"position":3,"rank_group":3,"rank_absolute":3,"url":"https://ahrefs.com/seo-api","not_found_reason":null}

Rank defaults to --depth 100, which checks the top 100 organic positions and costs 4 credits. Use --depth 10, --depth 20, or --depth 50 for cheaper top-N checks when that is enough. If found is false, the domain was not found within the checked depth.

Keep results small

Two flags keep SEOCTL friendly to an agent’s context window.

--limit caps how many rows a list command returns:

seoctl ideas "seo api" --country us --limit 10

--fields (or -f) keeps only the columns you name:

seoctl serp "best crm software" --limit 10 --fields position,title,domain

Ask for the smallest useful --limit, and reach for --fields on every SERP and domain command. If a requested field is unavailable for a result, SEOCTL returns it as null.

Country and language

Most commands accept a country code, and you can override the location or language directly:

seoctl volume "keyword research" --country us
seoctl volume "keyword research" --location-code 2840 --language en