docs

CLI Commands

Complete reference for all seofields CLI commands.

`init`

Adds seofields() to your sanity.config.ts or sanity.config.js file. Automatically detects your config file and injects the import and plugin registration.

Options

Flag	Description
--schema-org	Also inject `schemaOrg()` from `sanity-plugin-seofields`
--preview	Enable SEO preview in the plugin config
--dashboard	Explicitly enable the SEO Health Dashboard
--no-dashboard	Disable the SEO Health Dashboard

Examples

bash

# Add seofields() plugin
npx seofields init

# Add both seofields() and schemaOrg()
npx seofields init --schema-org

`config`

Update seofields() configuration options in your sanity.config file from the terminal. Supports dotted key notation for nested options.

Top-level Options

Flag	Description
--baseUrl=<url>	Base URL of your site
--titleSeparator=<sep>	Character between title and site name (e.g. `\|`, `–`)
--siteName=<name>	Default site name
--seoPreview=true\|false	Enable live Google-style preview

Health Dashboard Options

Flag	Description
--healthDashboard.licenseKey	License key for premium features
--healthDashboard.toolTitle	Custom title shown in Studio nav
--healthDashboard.showDocumentId	Show document _id in dashboard
--healthDashboard.query.types	Filter dashboard by document types (comma-separated)

Examples

bash

# Set base URL
npx seofields config --baseUrl=https://example.com

# Set license key
npx seofields config --healthDashboard.licenseKey=SEOF-XXXX-XXXX

# Multiple options at once
npx seofields config --healthDashboard.showDocumentId=true --seoPreview=true

# Filter dashboard by document types
npx seofields config --healthDashboard.query.types=post,page

`create-config`

Interactive wizard to scaffold a seofields.cli.ts or seofields.cli.js config file. Prompts for project ID, dataset, and token configuration.

What it does

Asks if you want TypeScript or JavaScript
Auto-detects your project ID and dataset from sanity.config
Lets you confirm or override each value
Asks how to provide your token (env var or hardcoded)
Generates and writes the config file

bash

npx seofields create-config

`report`

Queries your Sanity dataset and generates an SEO health report. Each document is scored across title, description, image, keywords, and Open Graph fields.

Options

Flag	Description
-p, --project-id <id>	Sanity project ID
-d, --dataset <name>	Dataset name
-t, --token <token>	Sanity API token
--types <types>	Comma-separated document types to include
--format <format>	Output format: `table` or `summary`

Score Thresholds

Excellent

90–100

Good

70–89

Fair

50–69

Poor

0–49

Examples

bash

# Basic report (uses CLI config)
npx seofields report

# Limit to specific document types
npx seofields report --types post,page

# Summary format (aggregated counts)
npx seofields report --format summary

# Override credentials
npx seofields report --project-id abc123 --dataset production

`export`

Exports all documents with SEO fields to JSON or CSV. Useful for audits, spreadsheet analysis, or backing up SEO data before migrations.

Options

Flag	Description
-p, --project-id <id>	Sanity project ID
-d, --dataset <name>	Dataset name
-t, --token <token>	Sanity API token
--types <types>	Comma-separated document types to export
-f, --format <format>	Output format: `json` or `csv`
-o, --output <path>	Save output to file (defaults to stdout)

Exported Fields

Each exported record includes these fields:

_id_typetitleslugseoScoreseoStatusissuesseoTitleseoDescriptionhasKeywordshasOpenGraphhasTwitterhasMetaImage_updatedAt

Examples

bash

# Export as JSON to stdout
npx seofields export

# Export as CSV and save to file
npx seofields export --format csv --output seo-audit.csv

# Export only blog posts as JSON
npx seofields export --types post --output posts-seo.json

`doctor`

Checks your local SEO setup and reports any configuration issues. Verifies the plugin is installed, dependencies are present, and config files exist.

Checks Performed

✓sanity.config.ts/js found
✓seofields() plugin registered in config
✓sanity peer dependency installed
✓react peer dependency installed
✓seofields.cli.ts/js config file present (informational)

bash

npx seofields doctor

Environment Variables

The CLI reads these environment variables (in addition to your CLI config file):

Variable	Description
SANITY_PROJECT_ID	Sanity project ID
SANITY_DATASET	Dataset name
SANITY_TOKEN	API token
NEXT_PUBLIC_SANITY_PROJECT_ID	Next.js-style project ID
NEXT_PUBLIC_SANITY_DATASET	Next.js-style dataset

These are automatically loaded from .env, .env.local, and .env.development.local in your project root.

Troubleshooting

"Could not determine Sanity project ID"

Run npx seofields create-config to create a seofields.cli.ts config file, or pass --project-id directly.

"seofields() is already registered in your config"

The init command detected an existing registration and skipped injection. This is expected behavior — no duplicates are added.

Report shows no documents

Ensure your API token has at least viewer access to the dataset, and that your documents include an seo field.

process.env values not resolving in seofields.cli.ts

Make sure the variable is defined in .env or .env.local. The CLI loads these files automatically at startup.

Was this page helpful?