Home/Docs

ClimbySEO documentation

Everything you need to connect Search Console, run your first audit, and ship higher-ranking content — in the cloud or self-hosted.

Introduction

ClimbySEO reads your Google Search Console data and uses AI to tell you exactly which pages to optimize, keep, or create — ranked by ROI. It clusters queries by search intent, builds topical maps, scores opportunities, and hands you a prioritized action plan.

There are two ways to run it:

  • Cloud — we host it, supply the AI credits, and handle updates. Sign up and connect Search Console.
  • Self-hosted — run the open-source stack on your own infrastructure with your own keys. Free, AGPL-3.0.

New here? Jump to the Quick start — you can have your first report in about ten minutes.

Quick start

The fastest path on the cloud plan:

  1. Create an account at signup.
  2. Connect a Search Console property with one OAuth click.
  3. Pick a property, set your minimum impressions threshold, and hit Run analysis.
  4. Watch progress live, then open the Opportunities view.

Prefer to self-host? See Self-hosting for the one-command Docker setup.

Connect Search Console

ClimbySEO requests read-only access to your Search Console data. It never writes to or changes your GSC account.

Cloud

From Settings → Integrations, click Connect Google Search Console and approve the read-only scope. Your verified properties appear in the project picker.

Self-hosted

Tokens are stored in the gsc_tokens table. You can connect via the UI, or provide a token directly. The client resolves tokens in this order:

  1. Database (gsc_tokens table)
  2. Filesystem (credentials/token.json)
  3. Environment variable (GSC_TOKEN_JSON)

You must own or have delegated access to the property in Search Console. ClimbySEO can only see what your Google account can see.

Run an audit

An audit pulls your queries and pages, scrapes content, clusters intent, fetches SERPs, and scores every page. It runs as a background job, so you can close the tab and come back.

Key settings:

  • Property — which verified site to analyze.
  • Minimum impressions — ignore ultra-low-volume pages (default 50).
  • Scope — primary language only by default; non-default locale folders can be toggled per language.

Via the CLI:

$ climbyseo gsc analyze --project mysite --site https://example.com --wait --follow

Reading results

Every analyzed page gets an opportunity score (0–100) and a verdict:

  • Optimize — ranking but leaving clicks on the table. Comes with concrete edits.
  • Create — an uncovered intent worth a brand-new article. Comes with a brief.
  • Keep — performing fine; leave it alone for now.

Pages are also clustered by intent — informational, commercial, transactional — so you write for what searchers actually want. Sort by score to start with the wins that move revenue first.

Topical maps

The topical map discovers the full keyword universe for your niche by combining Search Console, Semrush keyword research, and competitor sitemaps, then scores each cluster commercially. You instantly see which clusters you already cover and which you're missing.

Live-SERP conversion-surface scoring deprioritises keywords dominated by directories and map packs, so you focus on terms you can actually win.

Self-hosting

ClimbySEO ships as a Docker Compose stack: the Next.js app, PostgreSQL, Redis, and background workers. Bring your own OpenRouter and Search Console keys — nothing leaves your server.

# clone & launch the full stack $ git clone https://github.com/climbyseo/climbyseo $ cd climbyseo && cp .env.example .env $ docker compose up -d ✓ postgres ready ✓ redis ready ✓ climbyseo-web http://localhost:3000 ✓ workers analyzing…

Open http://localhost:3000, create your admin account, and connect Search Console.

Requires Docker and PostgreSQL. The app is database-backed — there is no SQLite mode.

Configuration

Configure the self-hosted app via environment variables in .env:

# Database (PostgreSQL required) DATABASE_URL=postgresql://user:pass@localhost:5432/climbyseo # Background jobs REDIS_URL=redis://localhost:6379 # Auth BETTER_AUTH_SECRET=your-secret BETTER_AUTH_URL=http://localhost:3000 # AI & data providers (bring your own) OPENROUTER_API_KEY=sk-or-... SERPER_API_KEY=...

LLM and SEO data providers are pluggable — swap OpenRouter for any compatible endpoint, or wire in your preferred SERP and backlink sources.

CLI & API

The climbyseo CLI is a token-authenticated client for the same API the web app uses. Every command emits structured JSON with --json, with stable exit codes — ideal for scripts and CI.

Configure

$ climbyseo login # or set env vars $ export CLIMBYSEO_URL=https://app.climbyseo.com $ export CLIMBYSEO_TOKEN=your-token

Common commands

$ climbyseo opportunities list --project mysite --min-score 80 --json $ climbyseo gsc analyze --project mysite --site https://example.com --wait

Escape hatch

Any API procedure can be called directly by dotted path, so you're never blocked waiting on new CLI surface:

$ climbyseo rpc database.getOpportunities --input '{"projectId":"…","limit":5}'

FAQ

What's the difference between cloud and self-hosted?

Same app. Cloud means we run the servers, supply AI credits, and ship updates. Self-hosted means you run the open-source code on your own infrastructure with your own keys — free, but you manage it.

Is my Search Console data safe?

Yes. We request read-only GSC access and never sell or share your data. On self-host, your data never leaves your server.

Do I need my own AI keys?

On cloud, no — AI usage is included. On self-host you bring your own OpenRouter (or compatible) key.

Which sites work?

Any site verified in Google Search Console — WordPress, custom, e-commerce, multilingual.

Still stuck? Contact us and we'll help you climb.