OpenSEO

https://github.com/every-app/open-seo
Admin
OpenSEO is an open-source, self-hostable SEO tool offering keyword research, domain insights,...
Tokens:240,556
Snippets:1,936
Trust Score:6.2
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Setup and Migration Commands

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Activates the exact pnpm version declared in package.json, installs dependencies with a frozen lockfile, and runs the local database migration. Run once per fresh local DB.

```sh
# Activates the exact pnpm version declared in package.json.
corepack enable
pnpm install --frozen-lockfile

# Run once per fresh local DB
pnpm run db:migrate:local
```

--------------------------------

### Run Locally - Option 1

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Starts the development server using the default script.

```sh
# Option 1
pnpm run dev
```

--------------------------------

### Install and Run Website and BadSEO Projects

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Installs dependencies and runs the marketing website (`web/`) and audit test site (`tests/badseo/`) as separate pnpm projects. Includes validation commands for each.

```sh
# Marketing website
pnpm --dir web install --frozen-lockfile
pnpm --dir web run dev
# Validate website changes
pnpm --dir web run types:check
pnpm --dir web run build

# Audit test site (keep the root dependencies installed for its audit harness)
pnpm --dir tests/badseo install --frozen-lockfile
pnpm --dir tests/badseo run dev
# Validate BadSEO changes
pnpm --dir tests/badseo run build
```

--------------------------------

### Hermes: Install SEO Coach skill

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

Run this command in your terminal to install the SEO Coach skill through the Hermes skills hub. Repeat with the names of other OpenSEO skills you want. Hub installations retain their source so Hermes can check for updates later.

```bash
hermes skills install every-app/open-seo/plugins/openseo/skills/seo-coach
```

--------------------------------

### Install all OpenSEO skills

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this option to install every OpenSEO skill.

```bash
npx skills add every-app/open-seo --skill '*'
```

--------------------------------

### Clone and install OpenSEO (upstream repo)

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Clones the upstream repository directly if you don't need a fork, then sets up the environment.

```bash
git clone https://github.com/every-app/open-seo.git
cd open-seo
corepack enable
pnpm install
```

--------------------------------

### Clone and install OpenSEO (forked repo)

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Clones your forked repository and sets up the environment with pnpm. Requires Node 22.6+ and pnpm (enabled via corepack).

```bash
git clone https://github.com/YOUR_GITHUB_USER/open-seo.git
cd open-seo
corepack enable
pnpm install
```

--------------------------------

### Install and choose interactively

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this option to have the installer show available skills and agents.

```bash
npx skills add every-app/open-seo
```

--------------------------------

### Update skills installed with the skills CLI

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

List installations and update OpenSEO skills by name. Use the names you actually installed and choose the same project or global scope; pass -g for global or -p for project skills. Back up personal edits before updating.

```bash
npx skills list
npx skills update seo-coach seo-audit
```

--------------------------------

### Clone repository and set up environment

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md

Clones the OpenSEO repository, changes into the directory, and copies the example environment file to .env. Required before starting the Docker container.

```bash
git clone https://github.com/every-app/open-seo.git
cd open-seo
cp .env.example .env
```

--------------------------------

### Run BadSEO app locally with pnpm

Source: https://github.com/every-app/open-seo/blob/main/tests/badseo/README.md

Install dependencies and start the Vite dev server for the BadSEO fixture app. The dev server serves on http://localhost:8787, and sitemap URLs should use that origin when running the audit locally.

```bash
# from the repository root
pnpm install --frozen-lockfile          # also needed by the audit harness
pnpm --dir tests/badseo install --frozen-lockfile
pnpm --dir tests/badseo run dev               # serves on http://localhost:8787
```

--------------------------------

### Install all skills for OpenAI Codex only

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this option to install all OpenSEO skills for Codex only.

```bash
npx skills add every-app/open-seo --skill '*' --agent codex
```

--------------------------------

### Copy environment file

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Copies the example environment file to .env for configuration.

```bash
cp .env.example .env
```

--------------------------------

### Install simple-issue-description skill

Source: https://github.com/every-app/open-seo/blob/main/docs/CONTRIBUTING.md

Install the `/simple-issue-description` skill using npx. This skill helps refine issues for easier review.

```sh
npx skills add every-app/open-seo --skill simple-issue-description
```

--------------------------------

### Install all skills for Claude Code only

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this option to install all OpenSEO skills for Claude Code only.

```bash
npx skills add every-app/open-seo --skill '*' --agent claude-code
```

--------------------------------

### Start OpenSEO with Docker Compose

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Starts the OpenSEO container in detached mode. The first start builds the app and may take 1-2 minutes; follow progress with `docker compose logs -f`.

```bash
docker compose up -d
```

--------------------------------

### Run Locally - Option 2 (Recommended)

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Creates a log file and runs the dev server with portless, which is great for worktrees and pipes logs to a fixed file for agent debugging.

```sh
# Option 2 (Recommended)
# This log file makes it easier for your coding agent to debug.
mkdir .logs
touch .logs/dev-server.log

# This command uses portless, which is great for worktrees. It also pipes logs to that fixed file, which is helpful for agent debugging output.
pnpm dev:agents
```

--------------------------------

### Start the dev server

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md

Starts the OpenSEO dev server as usual after configuring the Postgres provider.

```sh
pnpm dev
```

--------------------------------

### Skills CLI: Add public OpenSEO skills

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

Run this command for agents using the skills CLI to choose public OpenSEO skills interactively. Choose the current agent and your preferred installation scope. Skip this if the OpenSEO plugin already supplies your skills.

```bash
npx skills add https://github.com/every-app/open-seo/tree/main/plugins/openseo/skills
```

--------------------------------

### Install OpenSEO plugin in Codex CLI

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/codex-plugin.md

Run these commands in your terminal to add the OpenSEO marketplace, install the plugin, and log in. `codex mcp login` opens a browser to approve the connection. If it reports that `openseo` isn't found, restart Codex first — bundled MCP servers only register after a restart — then run `codex mcp login openseo` again.

```bash
codex plugin marketplace add every-app/open-seo
codex plugin add openseo@openseo
codex mcp login openseo
```

--------------------------------

### Build and deploy commands

Source: https://github.com/every-app/open-seo/blob/main/tests/badseo/README.md

Run `npm run build` to build the TanStack Start client and Worker bundles and typecheck the project. Then run `npm run deploy` to build and deploy via Wrangler to badseo.dev.

```bash
npm run build                          # Vite build + typecheck
```

```bash
npm run deploy                         # build + wrangler deploy → badseo.dev
```

--------------------------------

### Install OpenSEO plugin in Claude Code

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/ai-visibility-in-openseo.md

Adds the OpenSEO plugin marketplace and installs the openseo plugin in Claude Code. Use before asking the agent to research prompts or set up tracking.

```text
/plugin marketplace add every-app/open-seo
/plugin install openseo@openseo
```

--------------------------------

### Migrate Local Database

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Applies migrations to the local database.

```sh
pnpm run db:migrate:local
```

--------------------------------

### Create .env.selfhost from template

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Copies the deployment environment template to `.env.selfhost` for filling in required values.

```bash
cp deploy/.env.selfhost.example .env.selfhost
```

--------------------------------

### Run BadSEO Audit Harness

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Runs BadSEO's audit harness against a local dev server URL.

```sh
pnpm --dir tests/badseo run audit http://localhost:8787
```

--------------------------------

### Generate Database Migration

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Generates a new database migration.

```sh
pnpm run db:generate
```

--------------------------------

### Update Hermes hub skills

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

Check for updates and update each installed OpenSEO skill by name. Hermes skips locally edited skills by default; review edits before replacing and use --force only to discard them.

```bash
hermes skills check
hermes skills update seo-coach
```

--------------------------------

### Format BadSEO and Website Code

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Uses the root formatter for BadSEO and the website's own formatter for the web project.

```sh
# From the repository root
pnpm exec prettier --write "tests/badseo/**/*.{ts,tsx,json,jsonc,md}"
pnpm --dir web run format:write
```

--------------------------------

### Run OpenSEO skills in Claude Code

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/claude-code-plugin.md

Plugin skills are namespaced by the plugin name. Use these slash commands to run each of the twelve OpenSEO skills.

```text
/openseo:seo-project-setup
/openseo:seo-coach
/openseo:seo-audit
/openseo:ai-visibility-audit
/openseo:ai-prompt-research
/openseo:keyword-research
/openseo:keyword-clustering
/openseo:competitive-landscape
/openseo:competitor-analysis
/openseo:local-seo
/openseo:link-prospecting
/openseo:seo-report
```

--------------------------------

### Codex CLI: Sign in to OpenSEO MCP

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

Run this command to sign in to the OpenSEO MCP server after adding the plugin. Reload or restart Codex if the plugin is not available yet.

```bash
codex mcp login openseo
```

--------------------------------

### Generate Base64 API Key

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_DEVELOPMENT.md

Generates a base64-encoded `login:password` value for the `DATAFORSEO_API_KEY` environment variable.

```sh
printf '%s' 'YOUR_LOGIN:YOUR_PASSWORD' | base64
```

--------------------------------

### Prompt to choose an SEO task with OpenSEO

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/chatgpt.md

Use this prompt after a successful connection check to have OpenSEO help choose one SEO task for your website. It asks about your goal before starting paid research.

```text
Use OpenSEO to help me choose one SEO task for my website. Ask about my goal before starting paid research.
```

--------------------------------

### Update OpenSEO plugin in Codex

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/codex-plugin.md

Run this command to upgrade the OpenSEO marketplace. Reload or restart Codex if the updated skills are not available.

```bash
codex plugin marketplace upgrade openseo
```

--------------------------------

### Update OpenSEO to latest version

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Pulls latest changes, reinstalls dependencies, and redeploys. For forked repos, use `git fetch upstream && git merge upstream/main` instead of `git pull`.

```bash
git pull        # or: git fetch upstream && git merge upstream/main, if you forked
pnpm install
pnpm deploy:selfhost --yes
```

--------------------------------

### Troubleshoot OpenSEO MCP authentication in Codex

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/codex-plugin.md

If the MCP server doesn't authenticate, log out first and retry with these commands.

```bash
codex mcp logout openseo
codex mcp login openseo
```

--------------------------------

### Remove OpenSEO plugin from Codex

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/codex-plugin.md

Run this command to remove the OpenSEO plugin from Codex.

```bash
codex plugin remove openseo@openseo
```

--------------------------------

### Environment variables for migration script

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/runbooks/d1-to-postgres-detailed.md

Required credentials in .env.local for the migration script and db:migrate:pg. CLOUDFLARE_D1_DATABASE_ID is optional; otherwise read from wrangler.jsonc. Get account id from wrangler whoami.

```sh
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_API_TOKEN=...          # needs D1 read
POSTGRES_DATABASE_URL=postgres://user:pass@host:5432/db
# CLOUDFLARE_D1_DATABASE_ID=...   # optional; otherwise read from wrangler.jsonc
```

--------------------------------

### Remove OpenSEO plugin in Claude Code

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/claude-code-plugin.md

Run this command to uninstall the OpenSEO plugin from Claude Code.

```text
/plugin uninstall openseo@openseo
```

--------------------------------

### Start a Postgres container with Docker

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md

Runs a throwaway Postgres 16 container named openseo-postgres on host port 5433 to avoid clashing with a system Postgres on 5432. Sets the user, password, and database to openseo.

```sh
docker run --name openseo-postgres \
  -e POSTGRES_USER=openseo \
  -e POSTGRES_PASSWORD=openseo \
  -e POSTGRES_DB=openseo \
  -p 5433:5432 \
  -d postgres:16
```

--------------------------------

### Tear down Cloudflare deployment

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Deletes Workers, stage-suffixed D1/KV/R2 resources (including data), and the Access application.

```bash
pnpm alchemy destroy --env-file .env.selfhost --stage selfhost
```

--------------------------------

### Update manual Wrangler deployments

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE_LEGACY.md

Update steps for manual Wrangler deployments: pull latest code, install dependencies, and deploy. The deploy also deploys the open-seo-audit worker.

```bash
git pull
pnpm install
pnpm run deploy
```

--------------------------------

### Deploy OpenSEO to Cloudflare

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Provisions D1, KV, R2, applies migrations, deploys Workers, and creates Cloudflare Access application. Use `--yes` to skip prompts. If managing Access yourself, set TEAM_DOMAIN and POLICY_AUD in .env.selfhost.

```bash
pnpm deploy:selfhost --yes
```

--------------------------------

### Update Claude Code plugin

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/agent-setup.mdx

Run these commands inside Claude Code to update the OpenSEO plugin. Automatic updates can be enabled in /plugin → Marketplaces → openseo → Enable auto-update; third-party marketplaces have this off by default.

```text
/plugin marketplace update openseo
/plugin update openseo@openseo
/reload-plugins
```

--------------------------------

### Log in to Cloudflare with alchemy

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE.md

Logs in to Cloudflare and bootstraps alchemy's state-store Worker. Answer 'yes' to 'Customize OAuth scopes?' and enable access:write. If already logged in without access:write, run `pnpm alchemy login --configure`.

```bash
pnpm alchemy login                # answer yes to "Customize OAuth scopes?" and enable access:write
pnpm alchemy cloudflare bootstrap # deploys alchemy's state-store Worker to your account
```

--------------------------------

### Add upstream remote for deploy-button repos

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_CLOUDFLARE_LEGACY.md

One-time setup to add the upstream repository for deploy-button-created repos, allowing you to pull the newest code while keeping your local resource IDs.

```bash
git remote add upstream https://github.com/every-app/open-seo.git
```

--------------------------------

### Full Prompt: Rebuild a Competitor Set

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/competitor-set-is-wrong.md

Use this prompt with OpenSEO MCP to compare domains across a keyword set, strip brand terms, read pages and link profiles, and output a single document. Replace placeholders like [mydomain.com] and [what you sell] with your own details. The agent's page list is a sample on large sites; the Top Pages tab in the app has full numbers.

```text
My domain is [mydomain.com]. I sell [what you sell] to [who buys it].
Here are 10-20 terms I want to own: [paste].

1. Measure the set

Compare SERP competitors across those terms. Return every domain by
visibility, and for each one tell me whether it is an aggregator I should
get listed on, a publisher that owns the informational half, or a direct
competitor I could outrank.

2. Strip the brand terms

Pull ranked keywords for me and for the top 3 direct competitors with
brand terms excluded on both sides. Report the gap after that filter,
not before it.

3. Read the pages

For each of those 3 competitors, pull ranked keywords and group them by
landing URL so I get pages ordered by estimated traffic with the keyword
count per page. Tell me what business line each page serves, and flag
any page whose topic sits outside the market I named.

4. Read the link profiles

Give me referring domains rather than backlinks, the spam score, and
the broken backlinks and broken pages counts for each competitor.
Output the whole thing as one document.
```

--------------------------------

### Local preview deployment commands

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/preview-deployments.md

Commands to set up and deploy a local preview. `pnpm preview:access` deploys the persistent Access stack and always uses `--adopt`. `deploy:preview` builds with Vite's preview mode and runs `alchemy deploy` against `.env.preview`.

```sh
pnpm alchemy login    # once — see Credentials above
cp deploy/.env.preview.example .env.preview
pnpm preview:access   # once — the shared Access gate (safe to re-run)
pnpm deploy:preview --stage manual-preview --yes
```

--------------------------------

### Run the end-to-end audit with pnpm

Source: https://github.com/every-app/open-seo/blob/main/tests/badseo/README.md

Run the audit harness from the repository root with the BadSEO dev server running. It prints a per-page pass/fail matrix and an issue-type coverage line, and exits non-zero on any mismatch, so it works as a CI gate.

```bash
# from the repository root, with the BadSEO dev server running:
pnpm --dir tests/badseo run audit http://localhost:8787
```

--------------------------------

### OpenSEO MCP prompt: Search Console and rank tracker workflow

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/search-console-vs-rank-tracker.mdx

Use this prompt with the OpenSEO MCP to run a five-step workflow that combines Search Console data with rank tracker data. Steps 1-3 use no credits. Step 4 compares tracker positions with Search Console averages, and step 5 identifies discrepancies between the two lists.

```text
Using the OpenSEO MCP on project [name]:

1. Pull Search Console performance for the last 28 days by query and
   device. Show me the 20 queries with the most impressions, with
   position on mobile and on desktop side by side. Flag any query
   where the two positions differ by more than 5.

2. Pull the same 20 queries by query and page. For any query that
   returns two of my URLs, list both with their impressions.

3. Pull the last 16 months by date for the whole property and tell
   me whether impressions dropped by more than 30% in any single
   week, with the week.

4. Call get_rank_tracker for this project and list the tracked
   keywords with their latest mobile position and previous position.
   For each one that is also in the Search Console list, put the two
   positions in one row: tracker position, Search Console average.

5. Tell me which keywords I am tracking that Search Console shows no
   impressions for, and which Search Console queries with more than
   500 impressions I am not tracking.
```

--------------------------------

### OpenSEO MCP prompt for opportunity sizing and forecasting

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/opportunity-sizing-forecasting.mdx

Use this prompt with the OpenSEO MCP to size keyword clusters, forecast traffic, and convert to revenue. It requires live difficulty and volume data from the MCP. The prompt includes placeholders for topic, conversion rate, and conversion value, and outputs a document for review.

```text
Using the OpenSEO MCP, research keywords for "[my topic]" and cluster
the results by intent.

1. Size each cluster
For every cluster, report combined monthly volume, median keyword
difficulty, and the domains currently holding the top 3. Flag any
cluster where the top 3 are all sites I cannot realistically outrank.

2. Forecast a range
For the 5 most winnable clusters, model traffic at position 3,
position 5 and position 8 using a standard CTR curve. Show me
conservative, moderate and aggressive scenarios.

3. Convert to money
Apply a [2]% conversion rate and a [$400] conversion value to each
scenario. Rank the clusters by moderate-scenario revenue per unit of
difficulty, not by volume.

Output as a document I can review.
```

--------------------------------

### Migrate Postgres database

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/runbooks/d1-to-postgres-detailed.md

Run this command to provision and freshly migrate an empty Postgres database before running the migration script.

```sh
pnpm db:migrate:pg
```

--------------------------------

### Deploy a public-mirror PR locally

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/preview-deployments.md

For external PRs, build the fork's code in a detached worktree and deploy from the trusted checkout. Run these commands from the trusted checkout with .env.preview available. Verify the preview redirects to Access login before sharing.

```sh
git fetch https://github.com/every-app/open-seo.git pull/<pr>/head
git worktree add --detach ../open-seo-pub-<pr> FETCH_HEAD
cp .env.preview ../open-seo-pub-<pr>/
(cd ../open-seo-pub-<pr> && pnpm install --frozen-lockfile && pnpm exec vite build --mode preview)
rm -rf dist && cp -R ../open-seo-pub-<pr>/dist dist
git worktree remove --force ../open-seo-pub-<pr>
pnpm alchemy deploy --env-file .env.preview --stage pub-<pr> --yes
```

--------------------------------

### Full Prompt: Find the work only you can do

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/what-broke-the-99-dollar-ceiling.md

Use this prompt with the OpenSEO MCP to classify planned work items as EXECUTABLE or JUDGEMENT. Paste your list of planned work items where indicated. The prompt asks for data needed from OpenSEO for executable items and a key question for judgement items, returning the judgement list shortest first.

```text
Using the OpenSEO MCP, pull my current ranked keywords and top pages.

Then, for each item on this list of planned work:
  - <paste your list>

1. Classify it as EXECUTABLE (a model can complete it end to end) or
   JUDGEMENT (it needs a decision about positioning, audience, or tradeoffs).
2. For EXECUTABLE items, say what data you would need from OpenSEO to start.
3. For JUDGEMENT items, write the one question I have to answer first.
4. Return the JUDGEMENT list, shortest first.
```

--------------------------------

### Run a link gap analysis with OpenSEO MCP

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/backlink-gap-analysis.mdx

Use this prompt with the OpenSEO MCP to compare backlink profiles between your domain and a competitor. It pulls backlinks, referring domains, rank, and spam score, then identifies dofollow low-spam referring domains, cross-references them against yours, and checks broken backlinks for both domains. Run step 5 (broken backlinks on your own domain) before outreach to recover lost link equity.

```text
Using the OpenSEO MCP, compare the link profiles of
[mydomain.com] and [competitor.com].

1. Pull the backlinks overview for both. Report backlinks,
   referring domains, rank, and spam score side by side. Compute
   links per referring domain for each, and tell me what that
   ratio suggests about how their links were acquired.

2. Pull their backlink profile grouped one per domain, filtered
   to dofollow links with a low spam score. This is the
   shortlist, not the full list.

3. Cross-reference against my referring domains. Return the sites
   linking to them and not to me, sorted by domain authority, and
   for each one show which of their pages earned the link.

4. Separately, pull their broken backlinks: live links pointing
   at URLs on their domain that no longer resolve. For each,
   show the linking site and the dead target.

5. Run step 4 against my own domain too, and tell me how much of
   my own earned link equity currently lands on a 404.

For the step 3 list, judge each source on topical relevance to
my business first. Tell me which ones you would not approach and
why.
```

--------------------------------

### Weekly SEO Run with OpenSEO

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/seo-agent-change-log.md

Run this each week to have the agent follow the 'Change rules', review change logs, run due checks, propose improvements, and log changes after approval.

```text
Weekly SEO run for this project, using OpenSEO.

1. Read the project context and follow the "Change rules" section.
2. Read the change logs from the last 45 days. List the locked pages and the changes due for a check.
3. Run the due checks with Search Console data. If a change is worse at 30 days, show me the revert and wait for my OK.
4. From the last 28 days of Search Console data, pick up to five unlocked pages worth improving. Show me the numbers behind each pick.
5. Make the changes I approve, then save this week's change log.
```

--------------------------------

### OpenSEO MCP link prospecting prompt

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/how-to-get-backlinks.mdx

Use this prompt with the OpenSEO MCP to analyze your top pages, linking reasons, and find link prospects. It requires pasting Top Pages rows (URL and referring-domain count) from OpenSEO's Backlinks > Top Pages view. The prompt instructs the assistant to ask for rows if not supplied and to mark unreadable pages as unverified.

```text
Using the OpenSEO MCP on project [name], find where my next links
should come from, for [domain]:

1. Use the Top Pages rows I pasted to list my ten leading pages by
   referring domains. Read each page and classify it as a tool, an
   event or service page, an article, or a company page. Mark any
   unreadable page as unverified. If I have not supplied the rows,
   ask for them before continuing.

2. Call get_backlinks_profile for the two non-homepage URLs with the
   most referring domains in that list, using scope "page",
   mode one_per_domain, hideSpam true. Read the linking pages and
   suggest why each linked: cited data, used a tool, reported an
   event, listed a partner, or something else. Mark uncertain reasons
   as hypotheses and unreadable pages as unverified.

3. From those reasons, tell me which of my pages could earn more of
   the same kind of link, and what would have to be true for it to.

4. Pull Search Console performance by query for the last 3 months and
   list any query containing "calculator", "template", "checklist",
   "tool" or "estimate" where I have impressions. Those are tools
   people already want from me.

5. Give me a list of 20 businesses that share my customer and do not
   compete with me, from the referring domains I already have and the
   domains linking to my two closest competitors.
```

--------------------------------

### OpenSEO MCP automation prompt

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/what-to-automate.mdx

Use with the OpenSEO MCP to set up the schedule layer and define the agent's weekly job. The person answers the three questions in step 1. Step 5 returns the three layers; if a decision appears in the 'runs without me' list, that is the grass.

```text
Using the OpenSEO MCP on project [name]:

1. Ask me three questions and wait: which 20 to 40 keywords to
   track, which device, and what day of the week I read reports.

2. Call get_rank_tracker. If a tracker exists for my domain, add the
   keywords to it; otherwise create one: weekly, the device I named,
   depth 40. Call estimate_rank_tracker_cost first and show me the
   monthly figure before adding anything.

3. Call run_site_audit if the last audit is older than 30 days, and
   tell me when it will finish.

4. Write down, as a saved prompt I can paste every week: pull the
   tracker results, bucket the movement (entered top 3, entered page
   1, left page 1, unchanged), pull Search Console clicks for the
   tracked pages this week versus last, and write three sentences.

5. Tell me which of the things you just did will run again without
   me, which need me to paste the weekly prompt, and which need me to
   decide something.
```

--------------------------------

### Build one-page local SEO report with OpenSEO

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/local-seo-for-service-businesses.md

Use this prompt to generate a client-ready local SEO report for an agency or in-house team. It includes a profile audit, rank grids for top two services, a side-by-side with the main competitor, and one recommended fix, written in plain language for the owner.

```text
Use OpenSEO to build a one-page local SEO report for [client], a [trade]
in [town]. Include: their profile audit against the services they sell,
a 3x3 rank grid for their top two services, a side-by-side with whoever
wins the most points they lose, and one recommended fix. Write it for the
owner, not for an SEO: plain language, no jargon, and end with the date
we'll re-check.
```

--------------------------------

### Verify Postgres tables and rows

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md

Commands to inspect the Postgres database: list tables created by migrations and count rows in the projects table after app usage.

```sh
# Tables created by the migrations
docker exec openseo-postgres psql -U openseo -d openseo -c "\dt"

# Inspect rows the app writes (e.g. after creating a project / saving keywords)
docker exec openseo-postgres psql -U openseo -d openseo -c "select count(*) from projects;"
```

--------------------------------

### OpenSEO MCP prompt for referring domains report

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/referring-domains.mdx

Prompt for the OpenSEO MCP to generate a referring domains report. It uses get_backlinks_overview and get_backlinks_profile with specific parameters. Step 5 is the key number; step 2 flags own properties and directories to avoid over-reading the total.

```text
Using the OpenSEO MCP on project [name], report on referring domains
for [domain]:

1. Call get_backlinks_overview with scope "domain". Give me backlinks,
   referring domains, and the ratio between them.

2. From the top referring domains in that response, list the top 10
   by backlink count with their share of total backlinks. Flag any
   that are my own properties, my hosting or podcast platform, or a
   directory.

3. Call get_backlinks_profile with scope "domain", mode
   one_per_domain, sorted by firstSeen descending, page 1, 100 rows,
   hideSpam true. List the domains represented by backlinks first
   discovered in the last 30 days in this sample, with anchor text
   and target page. Do not call them newly acquired domains: the
   date belongs to the selected backlink, not the domain.

4. For each sampled domain, check whether its linking page is about
   the same topic as its target. Mark any you cannot verify.

5. Report the current referring-domain total, then the number of
   sampled domains with recent backlinks that appear relevant. Label
   the sample size and filters. Do not infer a monthly acquisition
   count from this sample.
```

--------------------------------

### OpenSEO MCP prompt for keyword tracking workflow

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/which-keywords-to-track.mdx

Use this prompt with the OpenSEO MCP to pull Search Console data, filter queries, and estimate rank tracker costs. Requires Search Console connected to the project and the OpenSEO MCP connected. Step 3 flags queries where two URLs appear, which can cause volatile tracker rows.

```text
Using the OpenSEO MCP on project [name]:

1. Pull Search Console performance for the last 3 months by query,
   all rows. Exclude queries containing the brand name, queries
   longer than 80 characters, and anything that looks like a tool
   ID or a prompt rather than a search.

2. Keep queries with average position between 4 and 20 and at least
   100 impressions. Sort by impressions. Show me the top 30 with
   position, impressions, and clicks.

3. Pull the same period by query and page, and for each of the 30
   tell me which URL Google is showing. Flag any query where two
   URLs both appear.

4. Call get_rank_tracker for this project. If a tracker exists for
   the site's domain, use it; otherwise create one with schedule
   weekly, devices mobile, depth 40.

5. Call estimate_rank_tracker_cost with additionalKeywordCount set
   to the number of terms I approve, and show me the per-check and
   monthly numbers before adding anything.
```

--------------------------------

### Configure MCP server in Cursor's mcp.json

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md

Add the OpenSEO server entry to your mcp.json file with the Authorization header containing your API key.

```json
{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp",
      "headers": {
        "Authorization": "Bearer oseo_YOUR_KEY"
      }
    }
  }
}
```

--------------------------------

### Build and run local image

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Builds a local Docker image from the Dockerfile and runs it with OPEN_SEO_IMAGE set to the local tag.

```bash
docker build -f deploy/docker/Dockerfile -t open-seo:local .
OPEN_SEO_IMAGE=open-seo:local docker compose up -d
```

--------------------------------

### Restart OpenSEO with Docker Compose

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_GOOGLE_SEARCH_CONSOLE.md

Recreates the OpenSEO container to apply new environment variables from .env. Required after changing configuration.

```bash
docker compose up -d --force-recreate open-seo
```

--------------------------------

### Prompt for finding SERP competitors via OpenSEO MCP

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/find-your-real-competitors.mdx

Use this prompt with the OpenSEO MCP to identify SERP competitors for a domain. It asks for a keyword set, exclusion of your own domain, and a categorized list of competitors. The final line flags unexpected results, which is the key value of this workflow.

```text
Using the OpenSEO MCP, find the SERP competitors for [mydomain.com].

1. Compare these keywords: [list 5-15 terms you actually want to
   own, including at least one modified the way a real buyer
   would modify it]. Exclude my own domain from the results.

2. Return the domains sorted by visibility, and for each one show
   which of my keywords it ranks for and at what position.

3. Sort the list into three groups:
   - direct competitors who sell what I sell
   - structural results (directories, marketplaces, review sites,
     video, retailers) that I am unlikely to outrank
   - accidental competitors ranking on a single strong page

4. For group three, tell me which single URL is ranking and what
   it would take to beat it.

Flag anything in the list I would not have guessed.
```

--------------------------------

### OpenSEO MCP prompt for keyword ranking report

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/keyword-ranking-report.mdx

Use this prompt with the OpenSEO MCP to generate a monthly ranking report. It instructs the assistant to pull tracker and Search Console data, bucket keywords, and highlight key movements. Note that step 4 requires judgment and thresholds can be adjusted, but the rule should be kept written down for consistency.

```text
Using the OpenSEO MCP on project [name], write this month's ranking
report for [company].

1. Call get_rank_tracker to list trackers, then read the relevant
   ones with trackerId. Pull every tracked keyword with position,
   previous position, and ranking URL. Label this section "Latest
   weekly ranking movement": the comparison uses a seven-day
   baseline, with an earliest-available fallback for sparse history.
   Do not present it as monthly movement or assume a full week of
   history when that is not established.

2. Pull Search Console performance for the last 28 days and the 28
   days before, by page, filtered to the URLs from step 1. Give me
   total clicks for both periods. That is the first sentence.

3. Bucket the keywords: entered top 3, entered page 1, left page 1,
   unchanged. Four counts.

4. Show me three rows: the largest position gain, the largest loss,
   and the keyword where position moved by 2 or less but Search
   Console clicks on its URL changed by more than 30%. Include SERP
   features for that third row.

5. Pull Search Console query data for the same two 28-day periods,
   filtered to the same URLs from step 1. Split reported queries into
   brand (containing "[brand]") and non-brand. Report non-brand clicks
   separately. Note that query totals can omit anonymized queries
   and differ from page totals.

6. Do not compute an average position across keywords. Do not
   invent a score. Put the full table in a separate block at the end.
```

--------------------------------

### Copy the skill files manually

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/skills/setup.md

Use this option to manually copy skill files into your agent's skills folder. Clones the repository and copies skills for Codex and Claude Code.

```bash
git clone https://github.com/every-app/open-seo.git

# Codex
mkdir -p ~/.codex/skills
cp -R open-seo/plugins/openseo/skills/* ~/.codex/skills/

# Claude Code
mkdir -p ~/.claude/skills
cp -R open-seo/plugins/openseo/skills/* ~/.claude/skills/
```

--------------------------------

### Connection check prompt for OpenSEO in ChatGPT

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/chatgpt.md

Send this prompt in a new chat with OpenSEO selected to verify the connection. ChatGPT should call OpenSEO and return your connection status and project list; an empty project list is also a successful check. These reads use no OpenSEO credits.

```text
Use OpenSEO to check my connection and list my projects. Do not run SEO research or create anything.
```

--------------------------------

### Re-run local rank grid with OpenSEO

Source: https://github.com/every-app/open-seo/blob/main/web/content/blogs/local-seo-for-service-businesses.md

Use this prompt to re-run a local rank grid after making profile changes, comparing point-by-point with a previous run. Specify the same center, size, spacing, and mobile setting to ensure comparability.

```text
Use OpenSEO to re-run my local rank grid for "[main service]": same center
([address]), same 3x3 size, same 8 km spacing, mobile. Compare it point by
point with my last run from [date]. Tell me which points moved, which
business holds #1 at each point now, and whether my profile changed in
between.
```

--------------------------------

### OpenSEO MCP prompt for competitor traffic analysis

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/competitor-traffic-estimates.mdx

Use this prompt with the OpenSEO MCP to correct a competitor's traffic estimate by analyzing pages instead of keywords. It instructs the MCP to pull domain overview data, identify stacked keyword groups, rank pages by traffic, and split them into competing and non-competing business lines. The final output must include a confidence statement.

```text
Using the OpenSEO MCP, give me an honest read on [competitor.com].

1. Pull the domain overview: estimated organic traffic and
   organic keyword count. Report these as the headline figures.

2. Pull their ranked keywords sorted by traffic. Find rows that
   share an identical search volume and identical traffic
   estimate and resolve to the same URL. Report roughly how much
   of the headline traffic sits in those stacked groups.

3. Group the keywords by ranking URL. Give me their top 20 pages
   by estimated traffic.

4. Split those pages into "in my business" and "other business
   line", where my business is [describe what you actually sell].
   Total each side.

Finish with two numbers: the headline estimate, and your best
estimate for the part of it that competes with me. Say how
confident you are and why.
```

--------------------------------

### Wait for Postgres to accept connections

Source: https://github.com/every-app/open-seo/blob/main/docs/LOCAL_POSTGRES.md

Checks readiness of the openseo-postgres container using pg_isready with the openseo user and database.

```sh
docker exec openseo-postgres pg_isready -U openseo -d openseo
```

--------------------------------

### OpenSEO MCP Prompt for Search Console Query Analysis

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/gsc-programmatic-discovery.mdx

Use this prompt with the OpenSEO MCP to pull Search Console query data and generate a work queue for programmatic discovery. It covers striking distance, zero-click pages, and gap analysis, outputting a document for review.

```text
Using the OpenSEO MCP, pull Search Console query data for
[mydomain.com] over the longest window available.

1. Striking distance
Filter to queries in positions 11-30 with more than [50] impressions.
Group them by the page that ranks, then sort each group by total
impressions. Give me the top 10 pages by recoverable impressions.

2. Zero-click pages
List pages with high impressions and a click-through rate under 1%.
For each, show the queries driving the impressions and tell me
whether they match the page's actual topic.

3. The gap
For my top 10 pages by clicks, compare total clicks against the sum
of clicks in the named-query table. Report the difference as a
percentage. Those are the pages where I am planning blind.

Output as a document I can review.
```

--------------------------------

### Add MCP server for Claude Code

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md

Use this command to add the OpenSEO MCP server to Claude Code with an API key. The key is passed via the Authorization header.

```bash
claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp --header "Authorization: Bearer oseo_YOUR_KEY"
```

--------------------------------

### Set API key and add MCP server for Codex CLI

Source: https://github.com/every-app/open-seo/blob/main/web/content/docs/mcp.md

Export the API key as an environment variable and add the MCP server using the --bearer-token-env-var flag.

```bash
export OPENSEO_API_KEY=oseo_YOUR_KEY
codex mcp add openseo --url https://app.openseo.so/mcp --bearer-token-env-var OPENSEO_API_KEY
```

--------------------------------

### Preview cleanup for local D1

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/runbooks/default-project-cleanup.md

Preview the cleanup for a local SQLite-backed D1 database named 'open-seo'.

```sh
pnpm cleanup:default-projects:d1 --database open-seo --local
```

--------------------------------

### Prompt for OpenSEO MCP to analyze Search Console data

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/run-seo-from-your-ai-assistant.mdx

Use this prompt with the OpenSEO MCP to have the assistant pull Search Console data, filter out irrelevant queries, and identify striking-distance opportunities. It includes steps to exclude brand queries and bot-like patterns, then rank queries by impressions. The exclusion count in step 2 is important for removing rows that would otherwise clutter the list.

```text
Using the OpenSEO MCP on project [name]:

1. Call get_project_context and tell me what the project already
   knows: goal, positioning, competitors, key pages. If it is empty,
   stop and ask me the four questions the seo-project-setup skill
   asks.

2. Pull Search Console performance for the last 3 months by query,
   all rows. Exclude queries containing the brand name and any query
   longer than 80 characters or containing "you are a" or a numeric
   ID followed by a colon. Tell me how many rows you excluded and
   show me three of them.

3. Keep queries at average position 4 to 20 with at least 100
   impressions. Sort by impressions. Show me the top 20 with clicks,
   impressions and position.

4. Pull the same period by query and page, and for the 20, tell me
   which URL ranks and whether any query shows two of my URLs.

5. Do not recommend content yet. Tell me which three of the 20 you
   would want to look at first and why, in one line each.
```

--------------------------------

### Deploy website manually with pnpm deploy:web

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/production-deployment.md

Runs the 'Deploy website' workflow manually. The workflow deploys the marketing site in `web/` as the `open-seo-landing` worker using wrangler, and runs automatically on merges to `main` that change `web/**`.

```sh
pnpm deploy:web
```

--------------------------------

### OpenSEO MCP prompt for intent research beyond Google

Source: https://github.com/every-app/open-seo/blob/main/web/content/marketing/library/intent-beyond-google.mdx

Use this prompt with the OpenSEO MCP to research keywords for a topic, split queries by surface, establish a branded baseline, and gather platform-specific vocabulary. It outputs a document for review.

```text
Using the OpenSEO MCP, research keywords for "[my topic]" and label
each result by intent.

1. Split by surface
Flag which of these queries an AI assistant can fully answer in a
paragraph, and which need a tool, a price, a login or a human. Rank
the second group higher: those are the queries that still produce a
visit.

2. Branded baseline
Pull my branded queries and their trend over the last 12 months. I am
going to invest in [platform], which sends no referral data, so I want
the branded line as my before-picture.

3. Vocabulary
For my top 10 non-branded queries, give me the phrasings a person
would use searching inside Pinterest or LinkedIn rather than Google:
shorter, more visual, more role-based.

Output as a document I can review.
```

--------------------------------

### Run protection tests, type check, and build

Source: https://github.com/every-app/open-seo/blob/main/docs/maintainers/FREE_TOOLS_PROTECTION.md

Run from the repository root to validate the free tool protection feature. The tests use mocked Siteverify responses for rejection paths and real local workerd/SQLite storage for concurrency, whole-run limits, rollback and persistence; they make no paid provider calls.

```sh
pnpm --dir web run test:protection
pnpm --dir web run types:check
pnpm --dir web run build
```

--------------------------------

### Pull latest image and restart

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Pulls the latest published image and restarts the container.

```bash
docker compose pull && docker compose up -d
```

--------------------------------

### Format BadSEO files with Prettier

Source: https://github.com/every-app/open-seo/blob/main/tests/badseo/README.md

Run Prettier from the repository root to format all BadSEO source files (TypeScript, TSX, JSON, JSONC, and Markdown).

```bash
pnpm exec prettier --write "tests/badseo/**/*.{ts,tsx,json,jsonc,md}"
```

--------------------------------

### Check Compose environment variables

Source: https://github.com/every-app/open-seo/blob/main/docs/SELF_HOSTING_DOCKER.md

Displays the resolved Docker Compose configuration to verify environment variables like AUTH_MODE and DATAFORSEO_API_KEY.

```bash
docker compose config
```

--------------------------------

### Restart development process after changing key

Source: https://github.com/every-app/open-seo/blob/main/docs/GOOGLE_MAPS_SETUP.md

Run this command to restart the development process after updating the GOOGLE_MAPS_API_KEY environment variable.

```sh
pnpm dev:agents
```
Tokens:
Raw