SEOgent CLI — Getting Started

The SEOgent CLI offers a command-line tool for running SEO scans and retrieving results from SEOgent. It's designed for both developers and AI agents.

Quick start for AI coding agents: Download the SEOgent SEO Skill to give your AI agent built-in SEO scanning capabilities — no manual setup required.

1. Create an API Token

Before using the CLI, you need an API token to authenticate your requests.

Log in to your SEOgent account
Navigate to Settings > API Tokens (/settings/api-tokens)
Enter a name for your token (e.g., "My CLI Token") and click Create
Copy the token immediately — it will only be shown once

Keep your token secure. Treat it like a password.

2. Install the CLI

Install the CLI globally via npm:

npm install -g seogent

Requires Node.js 18 or higher.

3. Authenticate

Choose one of three ways to provide your API token:

Option A: Save to config file (recommended for daily use)

seogent auth <your-api-token>

This stores your token in ~/.seogent/config.json with restricted file permissions.

Option B: Environment variable (recommended for CI/CD and agents)

export SEOGENT_API_KEY=<your-api-token>

Option C: Inline flag (one-off commands)

seogent scan https://example.com --api-key <your-api-token>

If multiple methods are set, the priority order is: --api-key flag > environment variable > config file.

4. Run Your First Scan

Start a scan on any URL:

seogent scan https://example.com

This returns a scan ID and exits immediately:

{
  "scan_id": "abc123",
  "status": "pending"
}

Limit pages discovered

seogent scan https://example.com --max-pages 50

Include Core Web Vitals

Add --performance to measure Largest Contentful Paint, Cumulative Layout Shift, Interaction to Next Paint, and other Core Web Vitals for every page scanned. Uses additional credits per page.

seogent scan https://example.com --performance

Check for dead links and broken images

Add --link-check to verify that every internal link and image on each page resolves successfully. Pages with broken links or missing images will be flagged in the results.

seogent scan https://example.com --link-check

You can combine both flags:

seogent scan https://example.com --performance --link-check

5. Check Scan Status

seogent status <scan_id>

Returns:

{
  "scan_id": "abc123",
  "status": "processing",
  "progress": 45,
  "url": "https://example.com",
  "created_at": "2026-02-17T12:00:00Z"
}

6. Get Scan Results

seogent results <scan_id>

Filter by section

seogent results <scan_id> --section meta

Show only issues

seogent results <scan_id> --issues-only

Filter by severity

seogent results <scan_id> --issues-only --min-severity high

7. Check Credit Balance

seogent credits

8. Pipe-Friendly Output

All commands output JSON to stdout, making them easy to compose with other tools:

# Extract issues with jq
seogent results abc123 | jq '.issues'

# Save results to a file
seogent results <scan_id> > results.json

Progress messages are sent to stderr so they don't interfere with JSON output. Use --quiet to suppress them entirely.

Command Reference

Command	Description
`seogent auth <key>`	Save your API token
`seogent auth --show`	Show the saved token (masked)
`seogent auth --remove`	Remove the saved token
`seogent scan <url>`	Start a scan (see scan flags below)
`seogent status <scan_id>`	Check scan progress
`seogent results <scan_id>`	Get scan results
`seogent credits`	Check credit balance

Scan Flags

Flag	Description
`--urls <url>`	Additional URLs to scan (repeatable)
`--mode <mode>`	Crawl mode: `discover` (default) or `manual`
`--max-pages <n>`	Maximum pages to scan (up to 10,000)
`--performance`	Include Core Web Vitals metrics
`--link-check`	Check for dead links and broken images
`--webhook <url>`	URL to POST results to when scan completes

Global Flags

Flag	Description
`--api-key <key>`	Override API token for this command
`--quiet`	Suppress all non-JSON output
`--help`	Show help for any command

Managing Your Tokens

You can manage your API tokens at any time from the SEOgent dashboard:

Create additional tokens for different environments (development, CI, production)
Revoke a token if it's compromised or no longer needed
Monitor when each token was last used

Navigate to Settings > API Tokens to manage your tokens.

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Authentication error (missing or invalid token)
`3`	Scan not found
`4`	Rate limit exceeded

Download the SEO Skill for AI Agents

Want to get started even faster? Download the SEOgent SEO Skill — a ready-made skill package that lets AI coding agents like Claude Code run SEO scans directly. Just drop it into your project and your agent can start scanning.