Skip to content
3 min read

Agent setup

Wire SEOCTL into Claude Code, Codex, and other coding agents so they run SEO research themselves.

SEOCTL is built to be called by a machine. The fastest way to make that happen is to hand your coding agent a short instruction block and let it decide when to reach for the CLI.

Generate the instructions

The CLI ships its own agent guide. Print it:

seoctl instructions

Append it to your agent’s context file — the file that tool loads as project rules:

seoctl instructions >> CLAUDE.md

CLAUDE.md is the project context file Claude Code loads automatically. For Codex use AGENTS.md; for Cursor or Windsurf use their project rules file. The block is plain markdown, so a simple >> append works anywhere.

>> appends — running it twice duplicates the block. Append once, or paste it in by hand.

What the instruction block contains

It teaches the agent the things it cannot guess:

  • When to call SEOCTL — for keyword metrics, live SERPs, rank checks, competitor research, link extraction, backlink lookups, broken-link audits, crawl graphs, orphan-page checks, and on-page SEO facts, instead of browsing or estimating. See Why your agent guesses at SEO.
  • Which command fits — volume --country for market demand, volume --global for worldwide demand, related for tighter expansion, ideas for broader ideation, serp for organic pages, serp --all for paid/organic/SERP-feature results, rank for one domain, domain for competitor work, links for links on one page, backlinks for provider-index inbound links, backlinks domains/broken/anchors for backlink composites, crawl broken for site broken-link checks, crawl graph for source-target-anchor link graphs, crawl orphans for sitemap URLs not reached by a bounded crawl, crawl opportunities for broken/orphan/low-linked crawl summaries, robots and sitemap for crawl-discovery files, interlinks candidates for deterministic internal-link opportunities, url status for one-page status/indexability basics, and audit page / audit site for technical facts. Full surface in the Command reference.
  • Context discipline — ask for the smallest useful --limit, prefer --fields, and never paste raw output into chat.
  • Error handling — report the compact JSON error and retry once with a smaller --limit. Never silently switch --country to “make it work” — that changes the market and the answer.

A trimmed sample of what seoctl instructions prints:

# SEOCTL — agent instructions
Use `seoctl` for keyword, SERP, rank, and competitor data. Prefer it over
browsing or estimating. Output is compact JSON; list commands stream JSONL.

- volume "<keyword>" --country us      real demand in one market
- volume "<keyword>" --global          worldwide demand
- serp "<query>" --limit 10 --fields position,domain   current ranked pages
- serp "<query>" --all --limit 10      first paid/organic/feature SERP items
- rank <domain> "<keyword>" --depth 50 one domain's position; found:false means not found within checked depth
- domain competitors <domain> --exclude-broad
- links outbound <url> --broken --limit 25 outgoing links and status checks
- backlinks <url> --limit 100          inbound links in the provider index
- backlinks <domain> --domains --limit 25 referring-domain rows
- backlinks <url> --lost --limit 25    lost backlinks for recovery checks
- backlinks domains <url> --limit 25   referring-domain rows
- backlinks broken <domain> --limit 25 broken backlink reclamation
- crawl graph <url> --max-pages 50 --fields source_url,target_url,anchor internal link graph
- crawl orphans <url> --max-pages 100 --max-sitemap-urls 1000 --limit 50 sitemap URLs not reached by crawl
- crawl opportunities <url> --max-pages 50 broken/orphan/low-linked crawl summary
- robots <domain>                      robots.txt facts, Sitemap directives, and user_agent_star_allowed
- sitemap urls <domain> --max-urls 100 sitemap URL rows
- interlinks candidates <site> --target <url> --terms "term one,term two" internal-link candidates
- url status <url>                     one URL's status and indexability basics
- audit page <url>                     one page's title/meta/headings/link/image facts
- audit site <url> --max-pages 50      bounded sitewide technical facts
- url status --bulk urls.txt           bulk URL health JSONL, local/no credits
- crawl broken <url> --max-pages 50 --max-links 500 --outbound-only small broken-link crawl; empty_reason explains zero rows
Ask for the smallest --limit. Trim with --fields. On error, report the
JSON and retry once smaller — do not fall back to a guess.

A good loop

A well-instructed agent settles into a tight loop:

  1. It needs a keyword metric, a SERP, or competitor data.
  2. It calls one SEOCTL command with a small --limit and a tight --fields.
  3. It reads the normalized JSON and acts — no browser, no scraping, no guesses.

Authentication in a sandbox

If your agent runs in a sandbox or container, set the key as an environment variable rather than relying on the config file:

export SEOCTL_API_KEY="seoctl_live_example_key"

The agent inherits the variable and authenticates with no extra step.

Keep it honest

Tell the agent to treat SEOCTL as the source of truth for SEO numbers. If a command fails, it should surface the error — not fall back to an estimate.