--- name: pp-surgegraph description: "SurgeGraph is the Answer Engine Optimization (AEO) platform that tracks AI citations, scores pages for citation readiness, and one-click fixes the gaps — now every workflow runs from the terminal or any agent. Trigger phrases: `what changed in SurgeGraph this week`, `AI Visibility for my project`, `which prompts lost AI citations`, `publish gap articles from a topic research`, `what knowledge libraries actually show up in citations`, `use surgegraph`, `run surgegraph`." author: "SurgeGraph Team" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - surgegraph-pp-cli --- # SurgeGraph — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `surgegraph-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install surgegraph --cli-only ``` 2. Verify: `surgegraph-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer): ```bash go install github.com/mvanhorn/printing-press-library/library/ai/surgegraph/cmd/surgegraph-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. ## When to Use This CLI Reach for this CLI when an agent needs to operate against SurgeGraph for any AI-search content task: monitoring AI Visibility deltas, drafting and publishing articles in bulk, auditing knowledge-library impact, or seeding another agent with a project's current state. Every visible web-app feature is also a CLI command, and every transcendence command is an MCP tool — the agent that opened the loop can close it without leaving the terminal. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Local state that compounds - **`visibility delta`** — See exactly what moved in AI Visibility week over week — overview, trend, sentiment, or traffic — without screenshotting two dashboard tabs and diffing them by hand. _Use this when the user asks what changed in AI Visibility or wants a movers report; it answers without burning a follow-up API roundtrip._ ```bash surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --metric overview,trend --agent ``` - **`visibility prompts losers`** — Surface tracked prompts whose citation count or first-position rank dropped vs the prior window — the report a CMO asks for every Monday and the dashboard can't produce. _Pick this when the user is hunting for visibility regressions; gives the agent a ranked, actionable list instead of two raw snapshots to compare._ ```bash surgegraph-pp-cli visibility prompts losers --project proj_abc123 --since 720h --agent --select prompt_id,prompt,citation_delta,position_delta ``` - **`visibility citation-domains rank-shift`** — Watch which domains gained or lost citation share for your project's AI-tracked prompts over a 30-day window — useful when a competitor starts crowding the answer set. _Use when monitoring competitive share-of-voice in AI answers._ ```bash surgegraph-pp-cli visibility citation-domains rank-shift --project proj_abc123 --window 720h --agent ``` - **`docs stale`** — List writer and optimized docs not updated in the last N days, ranked by recent AI-source traffic — the refresh queue in one query. _Use when prioritizing a content refresh queue._ ```bash surgegraph-pp-cli docs stale --project proj_abc123 --older-than 90 --agent --select document_id,title,last_updated,ai_traffic_30d ``` - **`visibility portfolio`** — Roll up AI Visibility deltas across every project in the organization — the agency-portfolio view the single-project UI doesn't produce. _Use when the user manages multiple projects (agency, multi-brand) and asks for an executive summary._ ```bash surgegraph-pp-cli visibility portfolio --window 168h --agent ``` - **`account burn`** — Project credit exhaustion from your last 30 days of usage snapshots — a pre-flight check before queueing a large bulk-publish run. _Pick this before kicking off a bulk operation to confirm you have credits._ ```bash surgegraph-pp-cli account burn --window 720h --agent ``` ### Cross-entity joins no single API call returns - **`knowledge impact`** — Rank a project's knowledge libraries by how often their grounded URLs actually appear in tracked AI citations — answers "is this library worth maintaining?". _Pick this when the user audits knowledge libraries or asks which library is paying off._ ```bash surgegraph-pp-cli knowledge impact --project proj_abc123 --agent ``` - **`research drift`** — Diff a topic_research's hierarchical map against the writer_documents you've already shipped — covered vs gap, ranked for action. _Use when planning a content sprint from a topic research; tells the agent exactly which subtopics still need articles._ ```bash surgegraph-pp-cli research drift --research-id res_xyz789 --project proj_abc123 --agent --select topic,parent,covered ``` - **`research domain diff`** — Set-diff a competitor's domain_research topic tree against your own topic_research — instant view of what they cover and you don't. _Pick this when comparing topical coverage against a named competitor._ ```bash surgegraph-pp-cli research domain diff --project proj_abc123 --mine res_xyz789 --theirs dom_res_aaa --agent ``` - **`visibility traffic-citations`** — For each top-traffic page, list the tracked prompts whose AI citations resolved to it — answers "why is this page getting AI traffic?". _Use when explaining traffic patterns or planning new content based on what's already pulling AI clicks._ ```bash surgegraph-pp-cli visibility traffic-citations --project proj_abc123 --agent --select page_url,ai_visits,citations ``` ### Compound workflows that span products - **`research gaps publish`** — Take topic-gap output, bulk-create documents in 50-doc batches, and queue them into a WordPress integration — one idempotent command for the content-ops ritual. _Pick this when the user wants to ship articles for every gap from a topic research; collapses a multi-tab manual workflow into one call._ ```bash surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run --agent ``` ### Agent-native plumbing - **`context bundle`** — Emit a JSON blob shaped for an agent's context window covering prompts, citations, docs, and topic-maps for one project — the handoff payload an agent's loop needs. _Use to seed another agent's working memory with everything you know about a SurgeGraph project, in one round-trip._ ```bash surgegraph-pp-cli context bundle --project proj_abc123 --include prompts,citations,docs,topics ``` - **`search`** — Full-text search across local cache: AI Visibility prompts, citations, writer documents, optimized documents, and topic-map nodes — one query, multi-entity hits. _Pick this when an agent needs to locate any signal — a prompt, a citation, a draft — across the whole local cache._ ```bash surgegraph-pp-cli search "AI search optimization" --kind prompts,citations,docs,topics --agent --select kind,id,title,snippet ``` - **`sync diff`** — Emit per-resource sync cursors and total row counts from the local store — the inspection primitive for agent loops that need to know whether a re-sync is due. _Run after `sync` to inspect cursor freshness, or in an agent loop to decide whether the local store needs to be re-synced before reading._ ```bash surgegraph-pp-cli sync diff --agent ``` ## Command Reference **create-ai-visibility-prompt** — Manage create ai visibility prompt - `surgegraph-pp-cli create-ai-visibility-prompt` — Create a new prompt to AI Visibility tracking. Prompts are tracked across AI answer engines to monitor brand... **create-api-key** — Manage create api key - `surgegraph-pp-cli create-api-key` — Create an LLM provider API key for the organization. The key is validated against the provider before being stored.... **create-bulk-documents** — Manage create bulk documents - `surgegraph-pp-cli create-bulk-documents` — Bulk create multiple AI-written documents in a single batch (max 50). Each article needs a prompt; all other... **create-document** — Manage create document - `surgegraph-pp-cli create-document` — Create and generate an AI-written document. Only 'prompt' is required — all other fields have sensible defaults.... **create-domain-research** — Manage create domain research - `surgegraph-pp-cli create-domain-research` — Start a domain research for topic coverage analysis. Analyzes a domain to discover relevant topics. Results are... **create-image** — Manage create image - `surgegraph-pp-cli create-image` — Generate an AI image and store it in the Content Vision gallery. Use get_content_vision_settings first to see... **create-knowledge-library** — Manage create knowledge library - `surgegraph-pp-cli create-knowledge-library` — Create a new knowledge library in a project. Knowledge libraries store documents that can be used as context for AI... **create-knowledge-library-document** — Manage create knowledge library document - `surgegraph-pp-cli create-knowledge-library-document` — Create a text document to a knowledge library. The document content will be indexed for use as AI writing context.... **create-optimized-document** — Manage create optimized document - `surgegraph-pp-cli create-optimized-document` — Create a content-optimized document from an existing WordPress post. The system fetches the post content via... **create-topic-research** — Manage create topic research - `surgegraph-pp-cli create-topic-research` — Start a topic research for topic coverage analysis. Analyzes a specific topic to discover subtopics, related... **create-topic-research-expansion** — Manage create topic research expansion - `surgegraph-pp-cli create-topic-research-expansion` — Expand an existing topic research by generating micro topics under one or more macro topics. Each macro topic... **delete-ai-visibility-prompt** — Manage delete ai visibility prompt - `surgegraph-pp-cli delete-ai-visibility-prompt` — Delete an AI Visibility prompt from a project. Use get_ai_visibility_prompts to find prompt IDs. Useful for cleaning... **delete-api-key** — Manage delete api key - `surgegraph-pp-cli delete-api-key` — Delete an API key from the organization. Use get_openai_keys / get_gemini_keys / get_anthropic_keys to find the... **delete-document** — Manage delete document - `surgegraph-pp-cli delete-document` — Delete a SurgeGraph document by ID. Use get_writer_documents or get_optimized_documents to find document IDs.... **delete-knowledge-library** — Manage delete knowledge library - `surgegraph-pp-cli delete-knowledge-library` — Delete a knowledge library and all its documents. Use get_knowledge_libraries to find library IDs. This is a hard... **delete-knowledge-library-document** — Manage delete knowledge library document - `surgegraph-pp-cli delete-knowledge-library-document` — Delete a document from a knowledge library. Removes the LlamaIndex indices, vector embeddings, and the document row.... **get-ai-visibility-citation-domain** — Manage get ai visibility citation domain - `surgegraph-pp-cli get-ai-visibility-citation-domain` — Drill into citations for a specific domain. Returns page-level URLs cited from that domain, which engines cited each... **get-ai-visibility-citation-own-domain** — Manage get ai visibility citation own domain - `surgegraph-pp-cli get-ai-visibility-citation-own-domain` — Retrieve citation data for the project's own domain. Shows which of the user's pages are being cited by AI engines,... **get-ai-visibility-citations** — Manage get ai visibility citations - `surgegraph-pp-cli get-ai-visibility-citations` — Retrieve high-level citation overview for AI Visibility tracking. Returns own-domain citation summary, per-engine... **get-ai-visibility-config** — Manage get ai visibility config - `surgegraph-pp-cli get-ai-visibility-config` — Retrieve AI Visibility tracking and answer engine configuration for a project. **get-ai-visibility-emerging-topics** — Manage get ai visibility emerging topics - `surgegraph-pp-cli get-ai-visibility-emerging-topics` — Retrieve emerging topics from AI Visibility tracking. Returns topics whose mention frequency is rising across AI... **get-ai-visibility-metadata** — Manage get ai visibility metadata - `surgegraph-pp-cli get-ai-visibility-metadata` — Retrieve filter metadata for an AI Visibility project. Returns the list of tracked answer engines (models), tracked... **get-ai-visibility-opportunities** — Manage get ai visibility opportunities - `surgegraph-pp-cli get-ai-visibility-opportunities` — Retrieve AI Visibility optimization opportunities for a project. Returns stats by priority and category, plus a list... **get-ai-visibility-overview** — Manage get ai visibility overview - `surgegraph-pp-cli get-ai-visibility-overview` — Retrieve AI Visibility overview for a specific brand in a project. Returns the brand's per-engine metrics... **get-ai-visibility-prompt-detail** — Manage get ai visibility prompt detail - `surgegraph-pp-cli get-ai-visibility-prompt-detail` — Deep dive into a single prompt on a specific date. Returns full brand performance (visibility, position, share,... **get-ai-visibility-prompt-response** — Manage get ai visibility prompt response - `surgegraph-pp-cli get-ai-visibility-prompt-response` — Retrieve the raw AI response for a specific prompt execution. Returns the structured response items and markdown... **get-ai-visibility-prompts** — Manage get ai visibility prompts - `surgegraph-pp-cli get-ai-visibility-prompts` — Retrieve prompts configured for AI Visibility tracking in a project. Paginated: defaults to page 1 with pageSize 50... **get-ai-visibility-response-structure** — Manage get ai visibility response structure - `surgegraph-pp-cli get-ai-visibility-response-structure` — Retrieve response structure analysis for a specific brand in AI Visibility tracking. Returns per-engine response... **get-ai-visibility-sentiment** — Manage get ai visibility sentiment - `surgegraph-pp-cli get-ai-visibility-sentiment` — Retrieve sentiment analysis for a specific brand in AI Visibility tracking. Returns per-engine sentiment... **get-ai-visibility-topic-gaps** — Manage get ai visibility topic gaps - `surgegraph-pp-cli get-ai-visibility-topic-gaps` — Retrieve topic gaps for AI Visibility tracking. Topic gaps are topics where competitors are mentioned but your brand... **get-ai-visibility-topics** — Manage get ai visibility topics - `surgegraph-pp-cli get-ai-visibility-topics` — Retrieve topic clusters from AI Visibility tracking. Returns clustered topics with keyword frequencies, trend... **get-ai-visibility-traffic-pages** — Manage get ai visibility traffic pages - `surgegraph-pp-cli get-ai-visibility-traffic-pages` — Retrieve paginated list of pages with AI traffic data. Returns per-page AI/human visits, CTR, crawl errors, top... **get-ai-visibility-traffic-summary** — Manage get ai visibility traffic summary - `surgegraph-pp-cli get-ai-visibility-traffic-summary` — Retrieve AI traffic analytics summary for a project. Returns total AI/human visits with trends, CTR, indexed pages,... **get-ai-visibility-trend** — Manage get ai visibility trend - `surgegraph-pp-cli get-ai-visibility-trend` — Retrieve daily AI Visibility trend for a specific brand. The date range must not exceed 14 days — the tool will... **get-anthropic-keys** — Manage get anthropic keys - `surgegraph-pp-cli get-anthropic-keys` — List all Anthropic API keys for the organization. Returns masked keys (last 4 chars visible), active status, label,... **get-author-brand** — Manage get author brand - `surgegraph-pp-cli get-author-brand` — Get the brand profile for a project (Author Synthesis). Returns brand identity values, mandatory/prohibited... **get-authors** — Manage get authors - `surgegraph-pp-cli get-authors` — List all authors configured for a project (Author Synthesis). Returns author profiles with voice calibration, bio,... **get-brand-mentions** — Manage get brand mentions - `surgegraph-pp-cli get-brand-mentions` — List all brand mentions configured for the organization. **get-content-vision-gallery** — Manage get content vision gallery - `surgegraph-pp-cli get-content-vision-gallery` — List images from the Content Vision gallery for a project. Supports filtering by type, style, search query, and... **get-content-vision-settings** — Manage get content vision settings - `surgegraph-pp-cli get-content-vision-settings` — Get Content Vision settings for a project including brand colors, featured image settings, and available image types... **get-document** — Manage get document - `surgegraph-pp-cli get-document` — Retrieve a single document by ID, including its content, AEO (AI Engine Optimization) suggestions, and SEO suggestions. **get-domain-research** — Manage get domain research - `surgegraph-pp-cli get-domain-research` — Get the full result of a domain research: the domain, extracted topics, and completion status. Use... **get-gemini-keys** — Manage get gemini keys - `surgegraph-pp-cli get-gemini-keys` — List all Gemini API keys for the organization. Returns masked keys (last 4 chars visible), active status, label, and... **get-knowledge-libraries** — Manage get knowledge libraries - `surgegraph-pp-cli get-knowledge-libraries` — List all knowledge libraries for a project. Returns libraries with document and chat counts. **get-knowledge-library-documents** — Manage get knowledge library documents - `surgegraph-pp-cli get-knowledge-library-documents` — List all documents/assets in a knowledge library. Returns document details including indexing status. **get-languages** — Manage get languages - `surgegraph-pp-cli get-languages` — List available languages for document creation and topic research. Returns language code and name. Pass the returned... **get-locations** — Manage get locations - `surgegraph-pp-cli get-locations` — List available locations (countries) for document creation and topic research. Returns location code, name, and... **get-openai-keys** — Manage get openai keys - `surgegraph-pp-cli get-openai-keys` — List all OpenAI API keys for the organization. Returns masked keys (last 4 chars visible), active status, label, and... **get-optimized-documents** — Manage get optimized documents - `surgegraph-pp-cli get-optimized-documents` — List optimized articles from Content Optimizer. Supports search and pagination. **get-organization-cms-integrations** — Manage get organization cms integrations - `surgegraph-pp-cli get-organization-cms-integrations` — List all CMS integrations connected to the organization, including which projects each integration is linked to.... **get-project-cms-integration** — Manage get project cms integration - `surgegraph-pp-cli get-project-cms-integration` — Get the CMS integration connected to a specific project. Returns the integration type, site details, and connection... **get-projects** — Manage get projects - `surgegraph-pp-cli get-projects` — List all projects for the organization. Supports search and pagination. **get-team** — Manage get team - `surgegraph-pp-cli get-team` — List all