Docs/CLI

CLI Reference

The BobBuilds CLI scaffolds blog pages into your codebase, pulls GEO reports, publishes content, and connects Claude, Codex, Cursor, or any MCP-compatible AI assistant to your workspace data — all from the terminal.

npx @bobbuilds/init --help

Installation

Use directly with npx — no global install needed. Requires Node.js 18+.

# One-time scaffold (interactive)
npx @bobbuilds/init

# Or install globally for repeated use
npm install -g @bobbuilds/init
bobbuilds-init --help

Set your API key as an env var to skip the prompt:

export BOBBUILDS_API_KEY=bb_live_your_key_here
export BOBBUILDS_API_BASE=https://app.bobbuilds.ai # optional

Commands

npx @bobbuilds/init chat

Open an interactive GEO agent in your terminal. Ask about your AI visibility in plain language — the agent calls live data tools and streams the answer. Maintains conversation history. Slash commands: /report, /clear, /help, /exit.

Flags

--key=bb_xxxrequiredBobBuilds API key

[question...]Optional question to start with

--api=https://...Override API base

Example

# Start the agent
npx @bobbuilds/init chat --key=bb_xxx

# Start with a first question
npx @bobbuilds/init chat "How do I compare to my competitors?" --key=bb_xxx

# With env var
BOBBUILDS_API_KEY=bb_xxx npx @bobbuilds/init chat

npx @bobbuilds/init ask

Ask the GEO agent a single question and stream the answer (non-interactive). Ideal for scripts and quick checks. Use --format=json for machine-readable output.

Flags

<question...>requiredYour question

--key=bb_xxxrequiredBobBuilds API key

--format=jsonOutput JSON instead of streamed text

--api=https://...Override API base

Example

# Ask one question
npx @bobbuilds/init ask "Why did my visibility drop last week?" --key=bb_xxx

# JSON for scripting
npx @bobbuilds/init ask "Top 3 fixes?" --key=bb_xxx --format=json | jq -r '.reply'

npx @bobbuilds/init init

Scaffold typed blog pages into your Next.js project. Detects App Router vs Pages Router automatically. Creates the listing page, single-post page (with JSON-LD + FAQs), webhook receiver, and .env.local.

Flags

--key=bb_live_xxxBobBuilds API key

--api=https://...Override API base URL

Example

# Interactive setup (recommended)
npx @bobbuilds/init init

# Creates:
# src/app/blog/page.tsx — Blog listing (ISR, 60s revalidate)
# src/app/blog/[slug]/page.tsx — Single post (SEO, JSON-LD, FAQs)
# src/app/api/bobbuilds-webhook/ — Auto-sync webhook
# .env.local — BOBBUILDS_API_KEY

npx @bobbuilds/init report

Print your latest GEO visibility report in the terminal. Shows overall score, provider breakdown, top-performing prompts, and weak prompts below the 50-point threshold.

Flags

--key=bb_live_xxxrequiredBobBuilds API key

--format=jsonOutput raw JSON instead of table

--api=https://...Override API base

Example

# Print report
npx @bobbuilds/init report --key=bb_live_xxx

# Output as JSON (pipe to jq, etc.)
npx @bobbuilds/init report --key=bb_live_xxx --format=json | jq '.weakPrompts'

# With env var
BOBBUILDS_API_KEY=bb_live_xxx npx @bobbuilds/init report

npx @bobbuilds/init blogs

List all published blogs for the workspace.

Flags

--key=bb_live_xxxrequiredBobBuilds API key

--format=jsonOutput raw JSON

Example

npx @bobbuilds/init blogs --key=bb_live_xxx

npx @bobbuilds/init publish

Publish all blogs in 'ready' status. Pass --slug to publish a single specific blog.

Flags

--key=bb_live_xxxrequiredBobBuilds API key

--slug=my-postPublish only this blog slug (optional — publishes all ready if omitted)

Example

# Publish all ready blogs
npx @bobbuilds/init publish --key=bb_live_xxx

# Publish one specific blog
npx @bobbuilds/init publish --key=bb_live_xxx --slug=best-crm-for-startups

npx @bobbuilds/init deliver

Push a published blog to an external webhook URL. BobBuilds signs the payload with HMAC-SHA256 if you provide a signing secret. The destination receives a JSON POST with the full blog content.

Flags

--slug=my-postrequiredBlog slug to deliver

--to=https://...requiredDestination webhook URL

--key=bb_live_xxxrequiredBobBuilds API key

--secret=s3cr3tHMAC signing secret (optional)

--publish=truePublish the blog before delivering if not already published

Example

npx @bobbuilds/init deliver \
 --slug=best-crm-for-startups \
 --to=https://mysite.com/api/bobbuilds-webhook \
 --key=bb_live_xxx \
 --secret=my_signing_secret

npx @bobbuilds/init mcp

Start an MCP (Model Context Protocol) server over stdio. Connect this to Claude Desktop, Cursor, Windsurf, Codex, or any MCP-compatible AI assistant. The server exposes 8 tools for querying your workspace data.

Flags

--key=bb_live_xxxrequiredBobBuilds API key (or BOBBUILDS_API_KEY env)

--api=https://...Override API base URL

Example

# Run directly (Claude will call this automatically from its config)
BOBBUILDS_API_KEY=bb_live_xxx npx @bobbuilds/init mcp

# Add to Claude Desktop config (~/.claude/claude_desktop_config.json):
# {
# "mcpServers": {
# "bobbuilds": {
# "command": "npx",
# "args": ["@bobbuilds/init", "mcp"],
# "env": { "BOBBUILDS_API_KEY": "bb_live_xxx" }
# }
# }
# }

npx @bobbuilds/init setup-mcp

Print the exact MCP config JSON for Claude Desktop, Cursor, Codex, and Windsurf. Copy-paste into your AI assistant's config file.

Flags

--key=bb_live_xxxBobBuilds API key

Example

npx @bobbuilds/init setup-mcp --key=bb_live_xxx

MCP Tools (available to AI assistants)

Once connected via the mcp command, your AI assistant can call these tools:

Tool	Description
`get_visibility_report`	Overall GEO score, provider breakdown, prompt performance
`list_blogs`	List all published blogs (filter by status)
`get_blog`	Full blog content, SEO metadata, FAQs, JSON-LD by slug
`publish_blog`	Mark a ready blog as published
`deliver_blog`	Push a blog to an external webhook URL
`list_prompts`	All tracked GEO prompts for this workspace
`get_prompt_performance`	Visibility score for a specific prompt across all providers
`get_sources`	Top cited sources shaping AI answers in your category

Example prompts for Claude / Codex once connected:

"What's my current GEO visibility score across all AI engines?"
"List all my ready blogs and publish them"
"Which prompts have a score below 50 and need new content?"
"Deliver the blog 'how-to-rank-in-chatgpt' to https://mysite.com/api/webhook"
"What are the top 10 sources being cited in my category?"
"Get the blog about AI visibility and show me its FAQ section"

Webhook payload schema

When BobBuilds delivers a blog (via deliver command or from the dashboard), it POSTs this JSON to your endpoint:

{
 "event": "blog.published",
 "sentAt": "2026-06-15T10:00:00.000Z",
 "blog": {
 "id": "uuid",
 "title": "How to Rank in ChatGPT: A Complete Guide",
 "slug": "how-to-rank-in-chatgpt",
 "contentMarkdown": "# How to Rank...",
 "contentHtml": "<h1>How to Rank...</h1>",
 "coverImageUrl": "https://...",
 "focusKeyword": "rank in chatgpt",
 "publishedAt": "2026-06-15T10:00:00.000Z",
 "createdAt": "2026-06-14T08:00:00.000Z",
 "seoMetadata": {
 "metaTitle": "How to Rank in ChatGPT — Complete 2026 Guide",
 "metaDescription": "Step-by-step guide to improving your brand...",
 "keywords": ["chatgpt seo", "rank in ai", "geo optimization"],
 "faqs": [
 { "question": "How does ChatGPT rank brands?", "answer": "..." }
 ],
 "jsonLd": { "@context": "https://schema.org", "@type": "BlogPosting", ... }
 }
 }
}

Verifying the HMAC signature:

// In your webhook handler
import { createHmac } from "node:crypto";

const sig = request.headers["x-bobbuilds-signature"]; // "sha256=abc123..."
const expected = "sha256=" + createHmac("sha256", SIGNING_SECRET)
 .update(rawBody)
 .digest("hex");

if (sig !== expected) throw new Error("Invalid signature");

AI Assistant Integrations

Claude Desktop

~/.claude/claude_desktop_config.json

{
 "mcpServers": {
 "bobbuilds": {
 "command": "npx",
 "args": ["@bobbuilds/init", "mcp"],
 "env": {
 "BOBBUILDS_API_KEY": "bb_live_xxx"
 }
 }
 }
}

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
 "mcpServers": {
 "bobbuilds": {
 "command": "npx",
 "args": ["@bobbuilds/init", "mcp"],
 "env": {
 "BOBBUILDS_API_KEY": "bb_live_xxx"
 }
 }
 }
}

Windsurf / Codex

codex.json or windsurf MCP settings

{
 "mcp": {
 "servers": {
 "bobbuilds": {
 "command": "npx",
 "args": ["@bobbuilds/init", "mcp"],
 "env": {
 "BOBBUILDS_API_KEY": "bb_live_xxx"
 }
 }
 }
 }
}

Custom agent / Hermes / OpenClaw

Any MCP-compatible client (stdio transport)

# Start the MCP server manually:
BOBBUILDS_API_KEY=bb_live_xxx npx @bobbuilds/init mcp

# Or programmatically (Node.js):
const { spawn } = require("child_process");
const mcp = spawn("npx", ["@bobbuilds/init", "mcp"], {
 env: { ...process.env, BOBBUILDS_API_KEY: key },
 stdio: ["pipe", "pipe", "inherit"],
});

← JS Embed REST API →