SEO Intel / Setup Guide
Setup Guide

SEO Intel Setup

Everything you need to install SEO Intel, configure AI models, connect data sources, and run your first competitive analysis. From zero to insights in 15 minutes.

Before you begin

Requirements

SEO Intel runs entirely on your machine. Here is what you need to get started.

Node.js 22.5+
Required. SEO Intel uses modern Node.js APIs. Download from nodejs.org
Ollama
Optional, for AI extraction. Runs LLMs locally on your hardware. Get Ollama
8 GB+ RAM
Recommended when running AI models locally. Crawling and analysis work with less.
Any OS
macOS, Windows, or Linux. The npm installation is identical on all platforms.
1

Installation

Install SEO Intel globally from npm

The fastest way to install SEO Intel is via npm. This gives you the seo-intel command globally.

Terminal
$ npm install -g seo-intel

Alternative: Install via ClawHub (if you use an agent harness that reads the ClawHub registry):

Terminal
$ clawhub install seo-intel

Verify the installation:

Terminal
$ seo-intel --version
# seo-intel v1.5.53

If you see a permission error on macOS/Linux, either fix your npm prefix (npm config set prefix ~/.npm-global) or use sudo npm install -g seo-intel.

2

Setup Wizard

Configure your project through a web-based interface

Run the setup command to launch the interactive configuration wizard in your browser:

Terminal
$ seo-intel setup
# Opens http://localhost:3000/setup in your default browser

The wizard walks you through:

  • Target domain — the site you want to analyze
  • Competitors — domains to crawl and compare against
  • AI model selection — which Ollama model to use for extraction
  • Crawl settings — depth limits, stealth mode, rate limiting

The wizard creates a .env file and SQLite database in your project directory. You can re-run seo-intel setup at any time to change settings.

3

License Key

Activate full features for Solo users

The free tier works without a license key. To unlock all features, purchase a Solo license:

Option A: Add to your .env file:

.env
SEO_INTEL_LICENSE=SI-xxxx-xxxx-xxxx-xxxx

Option B: Paste it directly in the setup wizard when prompted.

Verify activation:

Terminal
$ seo-intel status
# License: Solo (active)
# Domains: 3/unlimited
4

AI Models

Configure local and cloud AI for extraction and analysis

Local extraction uses Ollama to run models on your machine. No data leaves your computer.

Terminal — Install Ollama
# macOS / Linux
$ curl -fsSL https://ollama.com/install.sh | sh

# Or download from https://ollama.com for Windows/macOS app

Pull the recommended extraction model:

Terminal
$ ollama pull gemma4:e4b
ModelSizeSpeedBest for
gemma4:e2b6.7 GB~47 t/sBudget / fast extraction
gemma4:e4b8.9 GB~23 t/sBalanced (default)
qwen3.5:4b2.8 GB~60 t/sLow-RAM machines
qwen3.5:9b6.0 GB~30 t/sAlternative balanced

Configure in your .env file:

.env
# Ollama (local extraction)
OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=gemma4:e4b
OLLAMA_CTX=8192

Cloud models for analysis — the analyze command can use cloud LLMs for deeper insights. Add any of these to your .env:

Variable Provider Notes
GEMINI_API_KEY Google Gemini Cheapest option, good quality
ANTHROPIC_API_KEY Anthropic Claude Best quality analysis
OPENAI_API_KEY OpenAI GPT Widely available alternative

Cloud API keys are optional. Extraction works 100% offline with Ollama. Cloud models are only used by the analyze command for competitive analysis reports.

5

Google Search Console

Optional — import real search performance data

Connecting Google Search Console lets SEO Intel enrich its analysis with real click, impression, and ranking data from your site.

  • Go to the Google Cloud Console and create OAuth 2.0 credentials
  • Set the redirect URI to http://localhost:3000/oauth/callback
  • Enable the Search Console API for your project

Add the credentials to your .env:

.env
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Then authenticate:

Terminal
$ seo-intel gsc-auth
# Opens browser for Google OAuth flow
# Tokens are stored locally in .gsc-tokens.json

This step is entirely optional. SEO Intel works fully without Search Console data. You can connect it later at any time.

6

First Crawl

Run the full pipeline: crawl, extract, analyze, serve

With everything configured, run the four-step pipeline:

Terminal — Full pipeline
# 1. Crawl your target domain and competitors
$ seo-intel crawl

# 2. Extract SEO data from crawled pages using Ollama
$ seo-intel extract

# 3. Analyze competitive patterns with cloud AI
$ seo-intel analyze

# 4. Launch the dashboard
$ seo-intel serve

Here is what each command does:

  • crawl — visits every page on configured domains, stores HTML content, title, meta description, and body text in SQLite
  • extract — reads stored pages from the database (no network needed), uses Ollama to extract structured SEO data like headings, internal links, keyword usage, and content structure
  • analyze — sends extracted data to a cloud LLM for competitive analysis, gap detection, and actionable recommendations
  • serve — starts a local web server and opens the interactive dashboard where you can explore results, run new crawls, and generate reports

Use the --stealth flag with crawl (seo-intel crawl --stealth) for sites that block automated requests. Stealth mode uses Playwright with browser fingerprint randomization.

Reference

CLI Commands

Every command available in the SEO Intel CLI.

Command Description
seo-intel setup Launch the web-based setup wizard
seo-intel crawl Crawl configured domains and store pages in SQLite
seo-intel crawl --stealth Crawl with Playwright stealth mode enabled
seo-intel extract Extract SEO data from stored pages using Ollama (offline)
seo-intel analyze Run competitive analysis with cloud AI models
seo-intel serve Start the local dashboard server
seo-intel status Show license, project, and database status
seo-intel templates View detected URL pattern templates
seo-intel gsc-auth Authenticate with Google Search Console
seo-intel --version Print the installed version
seo-intel --help Show help for all commands and flags

Help

Troubleshooting

Common issues and how to fix them.

Your npm global bin directory is not in your PATH. Run npm config get prefix to find the prefix, then add [prefix]/bin to your shell PATH. On macOS/Linux, add export PATH="$(npm config get prefix)/bin:$PATH" to your ~/.zshrc or ~/.bashrc.

Make sure Ollama is running. Start it with ollama serve or launch the Ollama app. Check that your OLLAMA_URL in .env matches the Ollama address (default: http://127.0.0.1:11434). Verify the model is downloaded with ollama list.

Another process is using port 3000. Either stop it (lsof -ti:3000 | xargs kill on macOS/Linux) or SEO Intel will automatically try the next available port. The dashboard URL is printed in the terminal output.

This usually means the pages were crawled before v1.1.6 and have no stored body text. Re-crawl the domain with seo-intel crawl and then re-run extraction. If you have 8GB RAM, try a larger context window: set OLLAMA_CTX=16384 in your .env.

Make sure the key starts with SI- and is placed in the .env file in your project directory (not your home directory). Run seo-intel status to check where SEO Intel is looking for configuration. Ensure there are no extra spaces around the key.

Verify your OAuth credentials in the Google Cloud Console. Make sure the redirect URI is set to http://localhost:3000/oauth/callback exactly. Check that the Search Console API is enabled for your Google Cloud project. If tokens expire, re-run seo-intel gsc-auth.

SEO Intel requires Node.js 22.5 or later. Check your version with node --version. Use nvm to install and switch to the latest version: nvm install 22 && nvm use 22.

Frequently Asked Questions

FAQ

Common questions about installing and using SEO Intel.

Crawling and raw data are completely free — no time limits, no page caps. AI extraction, competitive analysis, and the dashboard require a Solo license (€9/month). You can test crawling without limits before purchasing. Enter your license key in the setup wizard (seo-intel setup).

No. SEO Intel runs entirely on your own machine. Crawling, AI extraction, and the dashboard all run locally. The only optional network connection is cloud AI (Gemini, Claude, GPT) for competitive analysis. All configuration — domains, models, API keys — is handled in the browser-based setup wizard.

The default recommendation is gemma4:e4b — a good balance of speed and quality. If RAM is limited (under 8 GB), use qwen3.5:4b. For faster runs, try gemma4:e2b. You can switch models anytime in the setup wizard (seo-intel setup) or manually in your .env file.

Yes. SEO Intel works on any operating system where Node.js 22.5+ is available: macOS, Windows, and Linux. Ollama is also available for all platforms.

The free tier has no limit on the number of sites you can crawl. With a Solo license, you can analyze your own site and up to five competitors per project. You can create unlimited projects.

Ahrefs and Semrush track SERP history — they tell you what already happened. SEO Intel analyzes content structure, entities, and AI citability to predict gaps before they show up in search results. It's a predictive tool, not a reactive one.

Yes, partially. Crawling, AEO scoring, and the dashboard work without Ollama. AI extraction (seo-intel extract) requires a local model — Ollama is the default backend, and LM Studio support is coming soon. Competitive analysis (seo-intel analyze) uses cloud AI, not Ollama.

No. All crawled data, extracted results, and analyses are stored in a local SQLite database on your machine. SEO Intel does not send data to external servers. Cloud AI analysis sends summarized data to your chosen AI provider only.

General product questions? See the SEO Intel product page FAQ.

Ready to start?

One command to get competitive intelligence running on your machine.

$ npm install -g seo-intel Copy