docs

seofields CLI

The seofields CLI is a developer toolkit bundled with the plugin. Manage SEO configuration, audit content health, and export data — all from your terminal.

Terminal — seofields

❯

Quick Start

bash

# Add seofields() to your sanity.config
npx seofields init

# Create a CLI config file (stores credentials)
npx seofields create-config

# Run an SEO health report
npx seofields report

# Check your setup
npx seofields doctor

Run SEO audits in CI

The CLI reads SANITY_PROJECT_ID, SANITY_DATASET and SANITY_TOKEN from the environment, so it runs unattended in a CI job. This workflow prints a summary report every Monday and stores a CSV export as a build artifact. Use a read-only API token.

.github/workflows/seo-report.yml

# .github/workflows/seo-report.yml
name: SEO report
on:
  schedule:
    - cron: "0 6 * * 1"   # every Monday
  workflow_dispatch:

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx seofields report --format summary
        env:
          SANITY_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
          SANITY_DATASET: production
          SANITY_TOKEN: ${{ secrets.SANITY_READ_TOKEN }}
      - run: npx seofields export --format csv --output seo-audit.csv
        env:
          SANITY_PROJECT_ID: ${{ vars.SANITY_PROJECT_ID }}
          SANITY_DATASET: production
          SANITY_TOKEN: ${{ secrets.SANITY_READ_TOKEN }}
      - uses: actions/upload-artifact@v4
        with:
          name: seo-audit
          path: seo-audit.csv

Commands

init

Add seofields() plugin to your sanity.config file

npx seofields init [--schema-org]

config

Update seofields() configuration options from the terminal

npx seofields config --baseUrl=https://example.com

create-config

Interactive wizard to create a seofields.cli.ts config file

npx seofields create-config

report

Generate an SEO health report for all documents

npx seofields report [--format table|summary]

export

Export all documents with SEO fields as JSON or CSV

npx seofields export --format csv --output audit.csv

doctor

Check plugin configuration, dependencies, and setup

npx seofields doctor

View all command options

CLI Config File

Instead of passing --project-id, --dataset, and --token on every command, create a seofields.cli.ts file in your project root:

seofields.cli.ts

// seofields.cli.ts
import { defineSeoCli } from "sanity-plugin-seofields/define-cli";

export default defineSeoCli({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  token: process.env.SANITY_READ_TOKEN,
});

Configuration reference

💡 Pro Tip

The CLI automatically loads .env, .env.local, and .env.development.local files. Use process.env.VAR_NAME in your config file and it will resolve at runtime.

Was this page helpful?