Get Started for Free
All posts
Guide

Running c:ideas and c:run From Your Own Repo

Wire the SearchFit content package into your Next.js or Astro repo. Step-by-step guide to running c:ideas and c:run locally for AI-optimized content that ranks

KKevin10 minutes read

The Problem: Your Content Is Invisible to AI Answer Engines

Your competitors are getting cited in ChatGPT, Perplexity, and Gemini while your site gets zero mentions. Every time a prospect asks an AI about your category, someone else’s brand shows up. That traffic is leaving your ecosystem, and it won’t come back unless you change how you produce content from your own repo.

SearchFit’s answer engine optimization platform tracks visibility across six AI engines and generates content engineered to rank in AI search at scale. Two commands, c:ideas and c:run, form the core of that workflow. c:ideas pulls an answer engine audit for any keyword, surfacing which citations the AIs pull today and what content gap you need to fill. c:run then generates an AI-first content package structured to get cited.

This tutorial shows you how to wire those two commands directly into your existing Next.js or Astro repository so your content team can run them without leaving the codebase.

Prerequisites

Before you start, confirm you have the following:

  • Node.js 18+ installed locally.
  • A Next.js or Astro project under Git version control. If you haven’t initialized a repository yet, Git Basics - Getting a Git Repository walks through the two-minute setup.
  • A SearchFit account with API access. You’ll need an API key or OAuth credentials. Read the OAuth and API Key Management in SearchFit guide to scope tokens properly.
  • Write access to the repository’s content directory (e.g., src/content in Astro or content/ in Next.js).
  • Familiarity with terminal-based CLIs and environment variables.

Step 1: Clone or Initialize Your Repository

If you already work inside a cloned repo, skip to Step 2. Otherwise, pull your project down to your local machine.

Once the repo is on your machine, navigate into it. Run git status to confirm everything is clean. If you’re starting from scratch, Setting up a repository gives a solid five-minute primer.

Step 2: Install the SearchFit CLI Package

SearchFit ships a Node.js CLI package that you can install globally or as a dev dependency. For repo-local installs, we recommend dev dependencies so the version stays pinned.

npm install -D @searchfit/cli
# or
yarn add -D @searchfit/cli

After installation, verify the binaries are available:

npx searchfit --version

If you see version output, the CLI is ready. If you’re integrating this into a monorepo, install the package at the root and alias the commands in your workspace scripts.

Pro tip: Lock the minor version exactly (@searchfit/[email protected]). The SearchFit team regularly improves the underlying agent orchestrator. You can read how the platform evolved from single prompts to multi-agent workflows in From Prompts to Agents: The Evolution of SearchFit's Content Engine.

Step 3: Authenticate the CLI With Your SearchFit Account

The CLI needs to talk to the SearchFit API to fetch audits and trigger generation. Two authentication methods are supported: API key (simpler for local dev) and OAuth (recommended for team environments).

API Key Method

  1. Log into the SearchFit dashboard.
  2. Go to Settings → API Keys and generate a key with content:read and content:write scopes.
  3. Export it in your terminal:
export SEARCHFIT_API_KEY=sk-xxxxxxxx

For persistent auth, add it to your .env.local file (make sure .env.local is in .gitignore). The CLI auto-loads dotenv files when they exist in the project root.

OAuth Method

For team accounts where multiple engineers run the commands, use the OAuth client credentials flow. The full token scoping, rotation, and auditing steps are covered in OAuth and API Key Management in SearchFit. Once you have a client ID and secret:

export SEARCHFIT_CLIENT_ID=...
export SEARCHFIT_CLIENT_SECRET=...

The CLI exchanges these for a short-lived access token automatically before each session.

If your team uses the SearchFit MCP server or the Claude plugin alongside the CLI, the same credentials work. See 10 Questions You Can Ask the SearchFit MCP Server and SearchFit Is Now Live on the Claude Plugin Marketplace for the full setup.

Warning: Never commit API keys or OAuth secrets. Pre-commit hooks should detect .env* files. On Astro projects, confirm the public/ directory does not accidentally include environment variable files.

Step 4: Understand c:ideas and c:run

Before executing, let’s look inside each command.

c:ideas

c:ideas sends a keyword to SearchFit’s auditor agent and returns a structured content brief. The brief includes:

  • Which AI engines currently cite content for this keyword (ChatGPT, Perplexity, Gemini, Claude, etc.)
  • Which competitor URLs are being cited
  • The exact semantic clusters the AIs prioritize
  • A recommended structure (headings, key terms, answer length)

This output mirrors the The AEO Content Brief Template Every Team Needs but is machine-readable so you can pipe it into generators.

c:run

c:run takes the brief (or a prompt referencing the brief) and passes it through SearchFit’s multi-agent content engine: researcher, writer, validator, and scorer. The output is a markdown article with inline AI citations mapped, an answer-first abstract, and entity-rich body text. The underlying orchestration is detailed in Multi-Agent Orchestration: The New Foundation of SearchFit and Inside the SearchFit Agent Team: Researcher, Writer, Validator, Scorer.

When you run c:run locally, it respects a .searchfit/config.yml that defines project-specific overrides, critical for Next.js or Astro integrations.

Step 5: Configure the Project for Next.js or Astro

SearchFit needs to know where your content lives and how to format output for your framework.

Create .searchfit/config.yml at the repo root:

project:
  name: my-saas-blog
  framework: astro   # or next
content_path: src/content/blog   # adjust for your project
output_format: markdoc          # or mdx
citation_format: inline_markdown
frontmatter:
  generate: true
  schema: astro-content-collection  # or next-mdx-remote
  • Astro users: Point content_path to your collection directory. Enable frontmatter generation with schema: astro-content-collection so the CLI outputs a slug, pubDate, and description compatible with Zod schemas.
  • Next.js users: If you use next-mdx-remote or Contentlayer, set schema: next-mdx-remote and output_format: mdx. The CLI will wrap the generated content in a proper MDX component.

Now, test the config:

npx searchfit validate-config

If anything is misconfigured, the validator agent will suggest fixes. The autonomous validation system is explained in Autonomous Content Validation: How Agents Score Their Own Work.

Step 6: Run c:ideas to Generate a Content Brief

Pick a keyword you want to rank for in AI search. Let’s use “best developer onboarding platform” as an example.

npx searchfit c:ideas "best developer onboarding platform"

The CLI streams the audit results in JSON:

{
  "keyword": "best developer onboarding platform",
  "engines": ["chatgpt", "perplexity", "gemini"],
  "current_citations": [
    {"url": "competitor-a.com/onboarding", "engine": "chatgpt"},
    {"url": "developer-b.com/guide", "engine": "perplexity"}
  ],
  "recommended_structure": {
    "title": "...",
    "h2s": ["..."],
    "entity_requirements": ["..."]
  },
  "brief_id": "brf_8a72c..."
}

You can save this to a file for repeat use:

npx searchfit c:ideas "best developer onboarding platform" --output brief.json

If you need to inspect the underlying agent prompts, the researcher agent’s logic is broken down in The Architecture of an AEO Agent Team.

Pro tip: Pipe the brief ID directly into a stub file that your CI can read. Many teams commit brief JSON into a content-plans/ directory to version-control their AEO strategy.

Step 7: Run c:run to Generate AI-Optimized Content

With a brief in hand (or referencing a keyword), generate the final article:

npx searchfit c:run --brief brief.json

Or generate directly from a keyword (the CLI will auto-run c:ideas first):

npx searchfit c:run "best developer onboarding platform"

The writer agent produces markdown, typically in under 90 seconds. The validator and scorer agents then check everything, no hallucinations, no made-up statistics, correct entity density. If the score is below your configured threshold (default 85), the generator re-runs until it passes. You can read about the scoring logic in How We Re-Ran 10,000 AEO Audits With Claude 4.7.

Output lands in the directory you defined in content_path. For an Astro project, you might see:

src/content/blog/best-developer-onboarding-platform.md

With frontmatter:

---
title: "Best Developer Onboarding Platform"
slug: "best-developer-onboarding-platform"
pubDate: 2025-04-10
description: "..."
citationMap:
  chatgpt: ["..."]
  perplexity: ["..."]
---

This structure plugs directly into Astro collections or Next.js MDX processing.

Step 8: Wire Into Your Dev Server

To make the workflow feel native to your framework, add npm scripts in package.json:

{
  "scripts": {
    "aeo:ideas": "searchfit c:ideas",
    "aeo:run": "searchfit c:run",
    "aeo:watch": "searchfit c:run --watch",
    "dev": "next dev"  // unchanged
  }
}

Now your team can run npm run aeo:ideas "some query" without knowing the CLI internals.

For Astro projects, you might tie the aeo:run output to a content collection hot reload. Astro’s dev server watches for file changes, so once the article lands in your src/content/blog/ directory, the preview updates automatically.

If you’re using a headless CMS alongside, consider which interface fits best. The Plugin vs Web App vs API: Which SearchFit Interface to Use When comparison helps you decide whether to supplement the CLI with the dashboard or API.

Step 9: Add Real-Time Citation Monitoring (Optional)

Once you publish the generated content, you’ll want to know if it starts getting cited. SearchFit’s citation monitoring API streams events.

Set up a polling script or webhook consumer in your repo:

// scripts/citation-monitor.js
import { SearchFit } from '@searchfit/api-client';

const client = new SearchFit({ apiKey: process.env.SEARCHFIT_API_KEY });

async function checkCitations() {
  const events = await client.citations.stream({
    site: 'yoursite.com',
    since: new Date(Date.now() - 60 * 60 * 1000) // last hour
  });
  for (const ev of events) {
    console.log(`${ev.engine} cited ${ev.url} for query "${ev.query}"`);
  }
}

checkCitations();

Add to your package.json:

"scripts": {
  "monitor:citations": "node scripts/citation-monitor.js"
}

Full integration instructions, including push-based webhooks to Slack or PagerDuty, are in Real-Time Citation Monitoring via the SearchFit API.

Step 10: Integrate Into CI/CD

For teams that want content generation as part of a deployment pipeline, wrap c:run in a GitHub Action or GitLab CI job.

Example GitHub Action:

name: Generate AEO Content
on:
  workflow_dispatch:
    inputs:
      keyword:
        required: true
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run c:run
        env:
          SEARCHFIT_API_KEY: ${{ secrets.SEARCHFIT_API_KEY }}
        run: npx searchfit c:run "${{ github.event.inputs.keyword }}"
      - name: Commit generated content
        run: |
          git config user.name 'searchfit-bot'
          git config user.email '[email protected]'
          git add src/content/blog/
          git commit -m "AEO content for ${{ github.event.inputs.keyword }}"
          git push

This workflow creates a new branch, generates content, and opens a PR for editorial review. The same pattern works in GitLab CI or Bitbucket Pipelines.

Warning: Always have a human approve generated content before publishing live. While the validator agent catches factual errors, tone and strategic alignment still benefit from editorial review.

Pro Tips for Engineers

  • Use --dry-run first. Before overwriting any files, preview the output with npx searchfit c:run "keyword" --dry-run. The CLI prints the markdown to stdout without writing.
  • Leverage the Claude plugin for exploration. While the CLI is best for batch generation, the SearchFit Claude Plugin lets you interactively explore AI citation landscapes. Use the 10 Prompts to Try With the SearchFit Claude Plugin to find high-value keywords before you commit them to the pipeline.
  • Audit existing content. You can point c:ideas at a URL instead of a keyword to audit an existing page: npx searchfit c:ideas --url https://yoursite.com/blog/old-post. It will tell you why that page isn’t cited and what to add.
  • Score thresholds. In .searchfit/config.yml, set min_score: 92 for high-stakes commercial pages and 70 for informational drafts. The scorer agent’s heuristics are explained in Autonomous Content Validation.
  • Combine with MCP server. If your team runs developer workflows inside VS Code or Cursor, the SearchFit MCP Server exposes the same data as the CLI but inside your editor’s AI chat.

How Marketing Teams Already Use This Workflow

The pattern of wiring SearchFit directly into the development repo has been adopted by content teams at B2B SaaS companies and agencies. Instead of toggling between a web dashboard and their CMS, they stay inside their codebase, keeping everything version-controlled. The full story of how marketing teams integrate SearchFit into their Claude workflows is described in How Marketing Teams Use SearchFit Inside Claude. For a broader guide on building an end-to-end AEO workflow inside Claude, see Building Your AEO Workflow Inside Claude.

Summary and Next Steps

You now have a production-ready setup that runs c:ideas and c:run from your own Next.js or Astro repository. That means every content pull request can include the exact AI visibility gap analysis and the generated article that fills it.

Key takeaways:

  • Install @searchfit/cli as a dev dependency and auth via scoped API key or OAuth.
  • Configure a .searchfit/config.yml to map content paths and framework-specific frontmatter schemas.
  • c:ideas surfaces citation gaps and structure recommendations per keyword.
  • c:run generates validated, AI-first markdown that plugs directly into your framework’s content layer.
  • Integrate into CI/CD for automated content generation with human approval gates.
  • Monitor citation events to close the feedback loop.

Start with one high-intent keyword that currently shows competitor citations in AI engines. Run c:ideas, scan the brief, execute c:run, and compare the generated output to your existing page. The traffic you’re currently losing to AI answer engines is trackable, and the fix is now scriptable.

For any setup issues, use npx searchfit validate-config or consult the internal guides linked throughout this article.

Get SearchFIT Weekly

What we are learning about getting brands cited in AI search, in your inbox every week. Unsubscribe any time.