SEOgent

SEOgent is an SEO auditing platform that crawls your website, analyzes every page against technical SEO and performance best practices, and delivers actionable recommendations to improve your search rankings.

This is the official command-line interface for the SEOgent API. Run full-site audits, scan individual pages, track issues over time, and integrate SEO checks into your CI/CD pipelines and automated workflows — all from the terminal.

Why SEOgent?

• Comprehensive audits — crawl entire sites via sitemap discovery or manual URL lists, with performance (Core Web Vitals) scanning built in
• Actionable results — every issue comes with severity ratings and clear guidance on how to fix it
• Automation-friendly — JSON output on stdout makes it trivial to pipe into jq, scripts, or AI agents
• Scale effortlessly — scan up to 10,000 pages per audit with cursor-paginated results

Built for AI Agents

SEOgent's CLI is designed to be a tool that AI coding agents can use autonomously. Every command returns structured JSON to stdout with human messages separated to stderr, so agents can parse results without any post-processing.

A typical agent workflow looks like this:

# Agent kicks off a scan
SCAN_ID=$(seogent scan example.com --quiet | jq -r '.scan_id')

# Agent polls until complete
while [ "$(seogent status "$SCAN_ID" --quiet | jq -r '.status')" != "completed" ]; do sleep 10; done

# Agent reviews issues filtered by severity
seogent results "$SCAN_ID" --issues-only --min-severity high

# Agent reads the JSON, identifies the affected files in the codebase,
# and opens a PR with fixes — all without human intervention

Because the CLI returns structured JSON, handles pagination, and uses deterministic exit codes, an agent doesn't need to manage any HTTP details. It can focus on what it does best: reading the audit results, mapping issues back to source code, and generating fixes.

Integration Examples

Claude Code / Cursor / Cline — Give your coding agent access to seogent as a tool and include instructions in your project's CLAUDE.md or system prompt:

You have access to `seogent` CLI for SEO auditing. After making changes to
pages, run `seogent scan <domain> --quiet` to start a scan, poll with
`seogent status <scan_id> --quiet`, and review output from
`seogent results <scan_id>`. Fix any high-severity issues before committing.

The agent can then autonomously scan, read the JSON output, locate the relevant source files, and apply fixes.

CI/CD gate — Add a scan to your deploy pipeline so SEO regressions are caught before they reach production:

# GitHub Actions example
- name: SEO audit
  env:
    SEOGENT_API_KEY: ${{ secrets.SEOGENT_API_KEY }}
  run: |
    SCAN_ID=$(npx seogent scan ${{ env.SITE_URL }} --quiet | jq -r '.scan_id')
    # Poll until scan completes
    while [ "$(npx seogent status "$SCAN_ID" --quiet | jq -r '.status')" != "completed" ]; do sleep 15; done
    npx seogent results "$SCAN_ID" --quiet > results.json
    # Fail the build if any critical issues are found
    HIGH=$(cat results.json | jq '[.top_issues[] | select(.severity == "critical" or .severity == "high")] | length')
    if [ "$HIGH" -gt 0 ]; then echo "$HIGH critical/high issues found" && exit 1; fi

Scheduled monitoring — Run a cron job that scans your site daily and pipes results to an agent or notification system:

# Scan nightly via webhook — results are POSTed to your endpoint when complete
0 3 * * * SEOGENT_API_KEY=sk_... seogent scan example.com --webhook https://your-app.com/api/seo-nightly --quiet

Webhook-driven — Start a scan with --webhook and let your backend handle the results asynchronously when the scan completes:

seogent scan example.com --webhook https://your-app.com/api/seo-callback

The key design principle: JSON stdout, human messages on stderr, and deterministic exit codes mean any automation layer — whether it's an AI agent, a shell script, or a CI runner — can reliably consume SEOgent output without parsing ambiguity.

More Information

For full documentation, pricing, and to create an account, visit seogent.ai.

Installation

npm install -g seogent

Requires Node.js 18 or later.

Authentication

Sign up at seogent.ai and generate an API token from your account settings.

seogent auth <your-api-token>

The token is saved to ~/.seogent/config.json. You can also authenticate per-command with --api-key or by setting the SEOGENT_API_KEY environment variable.

# Check which key is configured
seogent auth --show

# Remove saved key
seogent auth --remove

Usage

Start a scan

# Scan a domain (discovers pages automatically)
seogent scan example.com

# Scan specific URLs
seogent scan https://example.com/page --urls https://example.com/other

# Set crawl mode and max pages
seogent scan example.com --mode discover --max-pages 50

# Include performance metrics
seogent scan example.com --performance

# Include dead link and broken image detection
seogent scan example.com --link-check

# Combine add-ons
seogent scan example.com --performance --link-check

# Get notified via webhook when scan completes
seogent scan example.com --webhook https://your-app.com/api/callback

Check scan status

seogent status <scan_id>

Get results

# Full results
seogent results <scan_id>

# Only pages with issues
seogent results <scan_id> --issues-only

# Filter by severity
seogent results <scan_id> --min-severity high

# Paginate through results
seogent results <scan_id> --per-page 50 --cursor <next_cursor>

Cancel a scan

seogent cancel <scan_id>

List scans and domains

seogent scans
seogent scans --page 2
seogent domains

Check credit balance

seogent credits

Global Options

| Flag | Description | |------|-------------| | -k, --api-key <key> | API key (overrides env and config) | | -u, --api-url <url> | API base URL (default: https://seogent.ai) | | -q, --quiet | Suppress non-JSON stderr output |

Output

All command output is JSON on stdout, making it easy to pipe into other tools:

# Extract average score with jq
seogent results <scan_id> | jq '.average_score'

# Get top issues
seogent results <scan_id> --issues-only | jq '.top_issues'

Human-readable messages (progress, errors) go to stderr and can be silenced with --quiet.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication error (missing or invalid key) | | 3 | Not found | | 4 | Rate limited |