pp-surgegraph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SurgeGraph — Printing Press CLI

SurgeGraph — 印刷机CLI

Prerequisites: Install the CLI

前提条件：安装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:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press-library install surgegraph --cli-only

Verify:
```
surgegraph-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

bash

go install github.com/mvanhorn/printing-press-library/library/ai/surgegraph/cmd/surgegraph-pp-cli@latest

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能驱动

surgegraph-pp-cli

二进制文件。在调用本技能的任何命令之前，必须先验证CLI已安装。如果未安装，请先执行以下步骤：

通过印刷机安装程序安装：

bash

npx -y @mvanhorn/printing-press-library install surgegraph --cli-only

验证：
```
surgegraph-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等），可改用Go直接安装（要求Go 1.26.3或更高版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/ai/surgegraph/cmd/surgegraph-pp-cli@latest

如果安装后执行

--version

提示“command not found”，说明安装步骤未将二进制文件添加到

$PATH

中。在验证成功之前，请不要继续执行技能命令。

When to Use This CLI

何时使用本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.

当Agent需要针对SurgeGraph执行任何AI搜索内容任务时，可使用本CLI：监控AI可见性变化、批量起草和发布文章、审核知识库影响，或是将项目当前状态同步给其他Agent。Web应用的所有可见功能都对应一个CLI命令，所有超验命令都是MCP工具——开启循环的Agent无需离开终端即可完成闭环操作。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.

这些功能是其他同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
```

visibility delta
—— 精准查看AI可见度每周的变化情况，包括概览、趋势、情感或流量数据，无需手动截取两个仪表板标签页并对比差异。
当用户询问AI可见度有何变化或需要动态报告时使用此命令；无需额外调用API即可直接给出答案。
bash
```
surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --metric overview,trend --agent
```
visibility prompts losers
—— 找出与之前周期相比，引用量或首位排名下降的追踪提示词——这是CMO每周一都需要但仪表板无法生成的报告。
当用户查找可见度衰退情况时使用此命令；为Agent提供一份可操作的排名列表，而非需要手动对比的原始快照。
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
—— 观察30天周期内，哪些域名在项目AI追踪提示词的引用份额中上升或下降——当竞争对手开始挤占答案集合时非常有用。
用于监控AI答案中的竞品话语权份额。
bash
```
surgegraph-pp-cli visibility citation-domains rank-shift --project proj_abc123 --window 720h --agent
```
docs stale
—— 列出最近N天未更新的作者文档和优化文档，并按近期AI来源流量排序——一次查询即可得到内容刷新队列。
用于确定内容刷新的优先级。
bash
```
surgegraph-pp-cli docs stale --project proj_abc123 --older-than 90 --agent --select document_id,title,last_updated,ai_traffic_30d
```
visibility portfolio
—— 汇总组织内所有项目的AI可见度变化——单一项目UI无法提供的代理机构组合视图。
当用户管理多个项目（代理机构、多品牌）并需要执行摘要时使用。
bash
```
surgegraph-pp-cli visibility portfolio --window 168h --agent
```
account burn
—— 根据过去30天的使用快照预测积分消耗情况——在启动大规模批量发布前的预检操作。
在执行批量操作前使用此命令确认是否有足够积分。
bash
```
surgegraph-pp-cli account burn --window 720h --agent
```

Cross-entity joins no single API call returns

单次API调用无法实现的跨实体关联

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
```

knowledge impact
—— 按项目知识库中已落地URL在AI追踪引用中的实际出现频率排序——回答“这个知识库是否值得维护？”的问题。
当用户审核知识库或询问哪个知识库有回报时使用。
bash
```
surgegraph-pp-cli knowledge impact --project proj_abc123 --agent
```
research drift
—— 将主题研究的层级图与已发布的作者文档进行对比——区分已覆盖和存在差距的内容，并按优先级排序。
基于主题研究规划内容冲刺时使用；告知Agent哪些子主题仍需撰写文章。
bash
```
surgegraph-pp-cli research drift --research-id res_xyz789 --project proj_abc123 --agent --select topic,parent,covered
```
research domain diff
—— 将竞品的域名研究主题树与自身的主题研究进行差异对比——即时查看竞品覆盖而自身未覆盖的内容。
与指定竞品对比主题覆盖范围时使用。
bash
```
surgegraph-pp-cli research domain diff --project proj_abc123 --mine res_xyz789 --theirs dom_res_aaa --agent
```
visibility traffic-citations
—— 针对每个高流量页面，列出AI引用指向该页面的追踪提示词——回答“为什么这个页面能获得AI流量？”的问题。
用于解释流量模式或基于现有AI点击内容规划新内容。
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
```

research gaps publish
—— 获取主题差距输出，批量创建50份文档，并将其排入WordPress集成队列——将内容运营流程浓缩为一个幂等命令。
当用户想针对主题研究中的所有差距发布文章时使用；将多标签页的手动工作流简化为一次调用。
bash
```
surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run --agent
```

Agent-native plumbing

Agent原生管道

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
```

context bundle
—— 输出符合Agent上下文窗口格式的JSON blob，涵盖单个项目的提示词、引用、文档和主题图——Agent循环所需的交接负载。
用于通过一次调用将SurgeGraph项目的所有信息同步到其他Agent的工作内存中。
bash
```
surgegraph-pp-cli context bundle --project proj_abc123 --include prompts,citations,docs,topics
```
search
—— 在本地缓存中进行全文搜索：AI可见性提示词、引用、作者文档、优化文档和主题图节点——一次查询即可获取多实体结果。
当Agent需要在整个本地缓存中定位任何信号（提示词、引用、草稿）时使用。
bash
```
surgegraph-pp-cli search "AI search optimization" --kind prompts,citations,docs,topics --agent --select kind,id,title,snippet
```
sync diff
—— 输出本地存储中每个资源的同步游标和总行数——Agent循环中用于判断是否需要重新同步的检查原语。
在执行
```
sync
```
后运行以检查游标新鲜度，或在Agent循环中判断读取前是否需要重新同步本地存储。
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 team members and pending invitations for the organization. Returns member details including roles and...

get-topic-map — Manage get topic map

```
surgegraph-pp-cli get-topic-map
```
— Get the topic coverage map for a project. Returns the full topic hierarchy with pillar topics, subtopics, coverage...

get-topic-research — Manage get topic research

```
surgegraph-pp-cli get-topic-research
```
— Get the full result of a topic research: seed topic, location/language, and the hierarchical macro → micro topic...

get-usage — Manage get usage

```
surgegraph-pp-cli get-usage
```
— Get quota usage, feature limits, and credit balance for the organization. Shows permanent quotas (team seats,...

get-wordpress-authors — Manage get wordpress authors

```
surgegraph-pp-cli get-wordpress-authors
```
— List authors from a connected WordPress site. Returns id, name, slug, bio, and avatarUrl per author. Paginated —...

get-wordpress-categories — Manage get wordpress categories

```
surgegraph-pp-cli get-wordpress-categories
```
— List all categories from a connected WordPress site. Returns id, name, and slug for each category — use the ids...

get-wordpress-integrations — Manage get wordpress integrations

```
surgegraph-pp-cli get-wordpress-integrations
```
— List all WordPress integrations connected to the organization. Shows site details, masked API keys, and which...

get-writer-documents — Manage get writer documents

```
surgegraph-pp-cli get-writer-documents
```
— List articles from Content Hub. Supports filters and pagination.

get-writer-models — Manage get writer models

```
surgegraph-pp-cli get-writer-models
```
— List available AI models for document writing. Returns model IDs, providers, credit costs, and whether they support...

list-domain-researches — Manage list domain researches

```
surgegraph-pp-cli list-domain-researches
```
— List all domain researches for a project. Returns each entry with its id, domain, extracted topic count, and...

list-topic-researches — Manage list topic researches

```
surgegraph-pp-cli list-topic-researches
```
— List all topic researches for a project. Returns each entry with its id, seed topic, total topic count, and...

publish-document-to-cms — Manage publish document to cms

```
surgegraph-pp-cli publish-document-to-cms
```
— Publish a SurgeGraph document to the CMS connected to its project (currently WordPress). Creates a new post on the...

update-ai-visibility-prompt — Manage update ai visibility prompt

```
surgegraph-pp-cli update-ai-visibility-prompt
```
— Update an existing AI Visibility prompt. Can modify the prompt text, topic, and tags. Topics and tags are resolved...

update-api-key — Manage update api key

```
surgegraph-pp-cli update-api-key
```
— Update an existing API key. Can change the raw key, active status, label, or project assignments. Passing...

update-document — Manage update document

```
surgegraph-pp-cli update-document
```
— Update an existing SurgeGraph document's basic fields: title, content (HTML body), meta description, and/or schema...

update-project-cms-integration — Manage update project cms integration

```
surgegraph-pp-cli update-project-cms-integration
```
— Connect or change the CMS integration for a project (currently WordPress only). Use get_wordpress_integrations to...

create-ai-visibility-prompt —— 管理AI可见性提示词创建

```
surgegraph-pp-cli create-ai-visibility-prompt
```
—— 创建新的AI可见性追踪提示词。提示词会在AI答案引擎中被追踪，以监控品牌...

create-api-key —— 管理API密钥创建

```
surgegraph-pp-cli create-api-key
```
—— 为组织创建LLM提供商API密钥。密钥在存储前会先通过提供商验证....

create-bulk-documents —— 管理批量文档创建

```
surgegraph-pp-cli create-bulk-documents
```
—— 单次批量创建多篇AI生成文档（最多50篇）。每篇文章需要一个提示词；所有其他...

create-document —— 管理文档创建

```
surgegraph-pp-cli create-document
```
—— 创建并生成AI撰写的文档。仅需提供
```
prompt
```
参数——所有其他字段都有合理默认值....

create-domain-research —— 管理域名研究创建

```
surgegraph-pp-cli create-domain-research
```
—— 启动用于主题覆盖分析的域名研究。分析域名以发现相关主题。结果会...

create-image —— 管理图片创建

```
surgegraph-pp-cli create-image
```
—— 生成AI图片并存储到Content Vision图库中。请先使用get_content_vision_settings查看...

create-knowledge-library —— 管理知识库创建

```
surgegraph-pp-cli create-knowledge-library
```
—— 在项目中创建新的知识库。知识库存储可用作AI写作上下文的文档...

create-knowledge-library-document —— 管理知识库文档创建

```
surgegraph-pp-cli create-knowledge-library-document
```
—— 向知识库添加文本文档。文档内容会被索引，用作AI写作上下文....

create-optimized-document —— 管理优化文档创建

```
surgegraph-pp-cli create-optimized-document
```
—— 从现有WordPress帖子创建内容优化文档。系统通过...获取帖子内容

create-topic-research —— 管理主题研究创建

```
surgegraph-pp-cli create-topic-research
```
—— 启动用于主题覆盖分析的主题研究。分析特定主题以发现子主题、相关...

create-topic-research-expansion —— 管理主题研究扩展

```
surgegraph-pp-cli create-topic-research-expansion
```
—— 通过在一个或多个宏观主题下生成微观主题来扩展现有主题研究。每个宏观主题...

delete-ai-visibility-prompt —— 管理AI可见性提示词删除

```
surgegraph-pp-cli delete-ai-visibility-prompt
```
—— 从项目中删除AI可见性提示词。使用get_ai_visibility_prompts查找提示词ID。适用于清理...

delete-api-key —— 管理API密钥删除

```
surgegraph-pp-cli delete-api-key
```
—— 从组织中删除API密钥。使用get_openai_keys / get_gemini_keys / get_anthropic_keys查找...

delete-document —— 管理文档删除

```
surgegraph-pp-cli delete-document
```
—— 根据ID删除SurgeGraph文档。使用get_writer_documents或get_optimized_documents查找文档ID....

delete-knowledge-library —— 管理知识库删除

```
surgegraph-pp-cli delete-knowledge-library
```
—— 删除知识库及其所有文档。使用get_knowledge_libraries查找知识库ID。此操作不可撤销...

delete-knowledge-library-document —— 管理知识库文档删除

```
surgegraph-pp-cli delete-knowledge-library-document
```
—— 从知识库中删除文档。会移除LlamaIndex索引、向量嵌入和文档行....

get-ai-visibility-citation-domain —— 获取AI可见性引用域名详情

```
surgegraph-pp-cli get-ai-visibility-citation-domain
```
—— 深入分析特定域名的引用情况。返回该域名被引用的页面级URL、引用它们的引擎...

get-ai-visibility-citation-own-domain —— 获取项目自有域名的AI可见性引用数据

```
surgegraph-pp-cli get-ai-visibility-citation-own-domain
```
—— 检索项目自有域名的引用数据。显示用户的哪些页面被AI引擎引用...

get-ai-visibility-citations —— 获取AI可见性引用概览

```
surgegraph-pp-cli get-ai-visibility-citations
```
—— 检索AI可见性追踪的高级引用概览。返回自有域名引用摘要、各引擎...

get-ai-visibility-config —— 获取AI可见性配置

```
surgegraph-pp-cli get-ai-visibility-config
```
—— 检索项目的AI可见性追踪和答案引擎配置。

get-ai-visibility-emerging-topics —— 获取AI可见性新兴主题

```
surgegraph-pp-cli get-ai-visibility-emerging-topics
```
—— 检索AI可见性追踪中的新兴主题。返回在AI中提及频率上升的主题...

get-ai-visibility-metadata —— 获取AI可见性元数据

```
surgegraph-pp-cli get-ai-visibility-metadata
```
—— 检索AI可见性项目的过滤元数据。返回追踪的答案引擎（模型）列表、追踪...

get-ai-visibility-opportunities —— 获取AI可见性优化机会

```
surgegraph-pp-cli get-ai-visibility-opportunities
```
—— 检索项目的AI可见性优化机会。返回按优先级和类别划分的统计数据，以及列表...

get-ai-visibility-overview —— 获取AI可见性概览

```
surgegraph-pp-cli get-ai-visibility-overview
```
—— 检索项目中特定品牌的AI可见性概览。返回品牌的各引擎指标...

get-ai-visibility-prompt-detail —— 获取AI可见性提示词详情

```
surgegraph-pp-cli get-ai-visibility-prompt-detail
```
—— 深入分析特定日期的单个提示词。返回完整的品牌表现（可见性、排名、份额...

get-ai-visibility-prompt-response —— 获取AI可见性提示词响应

```
surgegraph-pp-cli get-ai-visibility-prompt-response
```
—— 检索特定提示词执行的原始AI响应。返回结构化响应项和markdown...

get-ai-visibility-prompts —— 获取AI可见性提示词列表

```
surgegraph-pp-cli get-ai-visibility-prompts
```
—— 检索项目中配置用于AI可见性追踪的提示词。支持分页：默认第1页，每页50条...

get-ai-visibility-response-structure —— 获取AI可见性响应结构

```
surgegraph-pp-cli get-ai-visibility-response-structure
```
—— 检索AI可见性追踪中特定品牌的响应结构分析。返回各引擎的响应...

get-ai-visibility-sentiment —— 获取AI可见性情感分析

```
surgegraph-pp-cli get-ai-visibility-sentiment
```
—— 检索AI可见性追踪中特定品牌的情感分析。返回各引擎的情感...

get-ai-visibility-topic-gaps —— 获取AI可见性主题差距

```
surgegraph-pp-cli get-ai-visibility-topic-gaps
```
—— 检索AI可见性追踪的主题差距。主题差距是指竞争对手被提及但自身品牌未被提及的主题...

get-ai-visibility-topics —— 获取AI可见性主题集群

```
surgegraph-pp-cli get-ai-visibility-topics
```
—— 检索AI可见性追踪的主题集群。返回包含关键词频率、趋势的集群主题...

get-ai-visibility-traffic-pages —— 获取AI可见性流量页面列表

```
surgegraph-pp-cli get-ai-visibility-traffic-pages
```
—— 检索带AI流量数据的页面分页列表。返回每页的AI/人工访问量、点击率、抓取错误、热门...

get-ai-visibility-traffic-summary —— 获取AI可见性流量摘要

```
surgegraph-pp-cli get-ai-visibility-traffic-summary
```
—— 检索项目的AI流量分析摘要。返回AI/人工总访问量及趋势、点击率、已索引页面...

get-ai-visibility-trend —— 获取AI可见性趋势

```
surgegraph-pp-cli get-ai-visibility-trend
```
—— 检索特定品牌的每日AI可见性趋势。日期范围不得超过14天——工具会...

get-anthropic-keys —— 获取Anthropic密钥列表

```
surgegraph-pp-cli get-anthropic-keys
```
—— 列出组织的所有Anthropic API密钥。返回掩码密钥（仅显示最后4位）、激活状态、标签...

get-author-brand —— 获取作者品牌信息

```
surgegraph-pp-cli get-author-brand
```
—— 获取项目的品牌档案（作者合成）。返回品牌标识值、必填/禁止...

get-authors —— 获取作者列表

```
surgegraph-pp-cli get-authors
```
—— 列出项目中配置的所有作者（作者合成）。返回包含语音校准、简介的作者档案...

get-brand-mentions —— 获取品牌提及列表

```
surgegraph-pp-cli get-brand-mentions
```
—— 列出组织中配置的所有品牌提及。

get-content-vision-gallery —— 获取Content Vision图库

```
surgegraph-pp-cli get-content-vision-gallery
```
—— 列出项目Content Vision图库中的图片。支持按类型、风格、搜索词过滤...

get-content-vision-settings —— 获取Content Vision设置

```
surgegraph-pp-cli get-content-vision-settings
```
—— 获取项目的Content Vision设置，包括品牌颜色、特色图片设置和可用图片类型...

get-document —— 获取文档详情

```
surgegraph-pp-cli get-document
```
—— 根据ID检索单个文档，包括其内容、AEO（AI引擎优化）建议和SEO建议。

get-domain-research —— 获取域名研究结果

```
surgegraph-pp-cli get-domain-research
```
—— 获取域名研究的完整结果：域名、提取的主题和完成状态。使用...

get-gemini-keys —— 获取Gemini密钥列表

```
surgegraph-pp-cli get-gemini-keys
```
—— 列出组织的所有Gemini API密钥。返回掩码密钥（仅显示最后4位）、激活状态、标签...

get-knowledge-libraries —— 获取知识库列表

```
surgegraph-pp-cli get-knowledge-libraries
```
—— 列出项目的所有知识库。返回包含文档和聊天计数的知识库信息。

get-knowledge-library-documents —— 获取知识库文档列表

```
surgegraph-pp-cli get-knowledge-library-documents
```
—— 列出知识库中的所有文档/资产。返回包含索引状态的文档详情。

get-languages —— 获取可用语言列表

```
surgegraph-pp-cli get-languages
```
—— 列出文档创建和主题研究的可用语言。返回语言代码和名称。传递返回的...

get-locations —— 获取可用地区列表

```
surgegraph-pp-cli get-locations
```
—— 列出文档创建和主题研究的可用地区（国家）。返回地区代码、名称...

get-openai-keys —— 获取OpenAI密钥列表

```
surgegraph-pp-cli get-openai-keys
```
—— 列出组织的所有OpenAI API密钥。返回掩码密钥（仅显示最后4位）、激活状态、标签...

get-optimized-documents —— 获取优化文档列表

```
surgegraph-pp-cli get-optimized-documents
```
—— 列出内容优化器中的优化文章。支持搜索和分页。

get-organization-cms-integrations —— 获取组织CMS集成列表

```
surgegraph-pp-cli get-organization-cms-integrations
```
—— 列出组织连接的所有CMS集成，包括每个集成关联的项目....

get-project-cms-integration —— 获取项目CMS集成

```
surgegraph-pp-cli get-project-cms-integration
```
—— 获取特定项目连接的CMS集成。返回集成类型、站点详情和连接...

get-projects —— 获取项目列表

```
surgegraph-pp-cli get-projects
```
—— 列出组织的所有项目。支持搜索和分页。

get-team —— 获取团队成员列表

```
surgegraph-pp-cli get-team
```
—— 列出组织的所有团队成员和待处理邀请。返回包含角色的成员详情...

get-topic-map —— 获取主题覆盖图

```
surgegraph-pp-cli get-topic-map
```
—— 获取项目的主题覆盖图。返回包含支柱主题、子主题、覆盖情况的完整主题层级...

get-topic-research —— 获取主题研究结果

```
surgegraph-pp-cli get-topic-research
```
—— 获取主题研究的完整结果：种子主题、地区/语言，以及宏观→微观的层级主题...

get-usage —— 获取使用情况

```
surgegraph-pp-cli get-usage
```
—— 获取组织的配额使用情况、功能限制和积分余额。显示永久配额（团队席位...

get-wordpress-authors —— 获取WordPress作者列表

```
surgegraph-pp-cli get-wordpress-authors
```
—— 列出连接的WordPress站点的作者。返回每个作者的ID、名称、别名、简介和头像URL。支持分页——...

get-wordpress-categories —— 获取WordPress分类列表

```
surgegraph-pp-cli get-wordpress-categories
```
—— 列出连接的WordPress站点的所有分类。返回每个分类的ID、名称和别名——使用ID...

get-wordpress-integrations —— 获取WordPress集成列表

```
surgegraph-pp-cli get-wordpress-integrations
```
—— 列出组织连接的所有WordPress集成。显示站点详情、掩码API密钥以及...

get-writer-documents —— 获取作者文档列表

```
surgegraph-pp-cli get-writer-documents
```
—— 列出内容中心的文章。支持筛选和分页。

get-writer-models —— 获取可用写作模型列表

```
surgegraph-pp-cli get-writer-models
```
—— 列出文档写作的可用AI模型。返回模型ID、提供商、积分成本以及是否支持...

list-domain-researches —— 列出域名研究

```
surgegraph-pp-cli list-domain-researches
```
—— 列出项目的所有域名研究。返回每个条目的ID、域名、提取的主题数量...

list-topic-researches —— 列出主题研究

```
surgegraph-pp-cli list-topic-researches
```
—— 列出项目的所有主题研究。返回每个条目的ID、种子主题、总主题数量...

publish-document-to-cms —— 将文档发布到CMS

```
surgegraph-pp-cli publish-document-to-cms
```
—— 将SurgeGraph文档发布到项目连接的CMS（目前仅支持WordPress）。在...创建新帖子

update-ai-visibility-prompt —— 更新AI可见性提示词

```
surgegraph-pp-cli update-ai-visibility-prompt
```
—— 更新现有AI可见性提示词。可修改提示词文本、主题和标签。主题和标签会被解析...

update-api-key —— 更新API密钥

```
surgegraph-pp-cli update-api-key
```
—— 更新现有API密钥。可更改原始密钥、激活状态、标签或项目分配。传递...

update-document —— 更新文档

```
surgegraph-pp-cli update-document
```
—— 更新现有SurgeGraph文档的基本字段：标题、内容（HTML正文）、元描述和/或Schema...

update-project-cms-integration —— 更新项目CMS集成

```
surgegraph-pp-cli update-project-cms-integration
```
—— 连接或更改项目的CMS集成（目前仅支持WordPress）。使用get_wordpress_integrations查找...

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

surgegraph-pp-cli which "<capability in your own words>"

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要做什么但不知道对应的命令时，可直接询问CLI：

bash

surgegraph-pp-cli which "<用你自己的话描述功能>"

which

会将自然语言功能查询解析为CLI精选功能索引中最匹配的命令。退出码

表示至少有一个匹配项；退出码

表示无匹配项——此时可使用

--help

或更精确的查询。

Recipes

使用示例

Monday AI Visibility review

周一AI可见度回顾

bash

surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --agent --select brand,metric,delta_pct

Pull week-over-week movers and pipe straight into the Monday CMO update.

bash

surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --agent --select brand,metric,delta_pct

提取每周变化数据，直接用于周一CMO更新报告。

Trim a deeply-nested citations response

精简深层嵌套的引用响应

bash

surgegraph-pp-cli get-ai-visibility-citations --project-id proj_abc123 --agent --select data.domains.domain,data.domains.citationCount

Citation responses are deeply nested; dotted-path

--select

keeps the payload under an agent's context budget.

bash

surgegraph-pp-cli get-ai-visibility-citations --project-id proj_abc123 --agent --select data.domains.domain,data.domains.citationCount

引用响应结构深层嵌套；使用点路径

--select

可将负载控制在Agent的上下文预算内。

Find every signal about a topic across the local cache

在本地缓存中查找与主题相关的所有信号

bash

surgegraph-pp-cli search "AI search optimization" --kind prompt,citation,doc,topic --agent --select kind,id,title,snippet

FTS5 across all four entities in one round-trip; results are unified and rankable. Run

sync

first to populate the index.

bash

surgegraph-pp-cli search "AI search optimization" --kind prompt,citation,doc,topic --agent --select kind,id,title,snippet

一次调用即可在四个实体中进行FTS5搜索；结果统一且可排序。运行前请先执行

sync

以填充索引。

Publish every gap topic to WordPress

将所有差距主题发布到WordPress

bash

surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run

Compounds get_topic_map → create_bulk_documents → publish_document_to_cms; idempotent on retries.

bash

surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run

整合get_topic_map → create_bulk_documents → publish_document_to_cms流程；重试时具有幂等性。

Filter results to one citation kind from the local cache

从本地缓存中筛选特定类型的引用信号

bash

surgegraph-pp-cli search "answer engine" --kind citation --agent

Limit FTS hits to one entity kind via

--kind

; combine with

--limit

to keep output bounded.

bash

surgegraph-pp-cli search "answer engine" --kind citation --agent

通过

--kind

限制FTS结果为单一实体类型；结合

--limit

控制输出规模。

Auth Setup

认证设置

SurgeGraph uses OAuth 2.1 against https://mcp.surgegraph.io with Authorization Code + PKCE + Dynamic Client Registration. Run

surgegraph-pp-cli auth login

once; the CLI registers a client, walks you through the browser flow, and stores the bearer plus refresh token for subsequent calls.

auth status

shows the current TTL and

auth logout

clears it.

Run

surgegraph-pp-cli doctor

to verify setup.

SurgeGraph 使用 OAuth 2.1 针对 https://mcp.surgegraph.io 进行认证，采用授权码 + PKCE + 动态客户端注册模式。运行

surgegraph-pp-cli auth login

一次即可；CLI会注册客户端，引导你完成浏览器流程，并存储Bearer令牌和刷新令牌用于后续调用。

auth status

显示当前TTL，

auth logout

清除认证信息。

运行

surgegraph-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
surgegraph-pp-cli create-ai-visibility-prompt --intent example-value --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Non-interactive — never prompts, every input is a flag
Explicit retries — use
```
--idempotent
```
only when an already-existing create should count as success

在任何命令后添加

--agent

参数。等效于：

--json --compact --no-input --no-color --yes

。

可管道化 —— 标准输出为JSON，错误输出到标准错误
可筛选 ——
```
--select
```
保留字段子集。点路径可深入嵌套结构；数组会遍历每个元素。对于冗长的API，这是控制上下文大小的关键：
bash
```
surgegraph-pp-cli create-ai-visibility-prompt --intent example-value --agent --select id,name,status
```
可预览 ——
```
--dry-run
```
显示请求但不发送
非交互式 —— 从不提示，所有输入均通过标志参数提供
显式重试 —— 仅当已存在的创建操作应视为成功时使用
```
--idempotent
```

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

surgegraph-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
surgegraph-pp-cli feedback --stdin < notes.txt
surgegraph-pp-cli feedback list --json --limit 10

Entries are stored locally at

~/.surgegraph-pp-cli/feedback.jsonl

. They are never POSTed unless

SURGEGRAPH_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

SURGEGRAPH_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当你（或Agent）发现本CLI存在问题时，可记录反馈：

surgegraph-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
surgegraph-pp-cli feedback --stdin < notes.txt
surgegraph-pp-cli feedback list --json --limit 10

反馈条目存储在本地

~/.surgegraph-pp-cli/feedback.jsonl

文件中。仅当设置了

SURGEGRAPH_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置

SURGEGRAPH_FEEDBACK_AUTO_SEND=true

时，才会发送反馈。默认仅存储在本地。

请记录让你感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这样的反馈才更有价值。

Output Delivery

输出传递

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都支持

--deliver <sink>

参数。输出会发送到指定的接收器，同时（或替代）输出到标准输出，以便Agent无需手动管道即可路由命令结果。支持三种接收器：

接收器	效果
`stdout`	默认；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出体POST到指定URL（ `application/json` 格式；若使用 `--compact` 则为 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误，并列出支持的接收器类型。Webhook失败时返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

surgegraph-pp-cli profile save briefing --json
surgegraph-pp-cli --profile briefing create-ai-visibility-prompt --intent example-value
surgegraph-pp-cli profile list --json
surgegraph-pp-cli profile show briefing
surgegraph-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时，可使用此功能——即HeyGen的“Beacon”模式。

surgegraph-pp-cli profile save briefing --json
surgegraph-pp-cli --profile briefing create-ai-visibility-prompt --intent example-value
surgegraph-pp-cli profile list --json
surgegraph-pp-cli profile show briefing
surgegraph-pp-cli profile delete briefing --yes

显式标志参数始终优先于配置文件值；配置文件值优先于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便内省Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	速率限制（等待后重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
surgegraph-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

：

为空、
help
或
--help
→ 显示
```
surgegraph-pp-cli --help
```
输出
以
install
开头 → 若以
```
mcp
```
结尾 → MCP安装；否则 → 参见上方前提条件
其他情况 → 直接使用（添加
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

bash

claude mcp add surgegraph-pp-mcp -- surgegraph-pp-mcp

Verify:

claude mcp list

从本CLI的公开库条目或预构建版本安装MCP二进制文件，然后注册：

bash

claude mcp add surgegraph-pp-mcp -- surgegraph-pp-mcp

验证：

claude mcp list

Direct Use

直接使用

Check if installed:
```
which surgegraph-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

surgegraph-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
surgegraph-pp-cli <command> --help
```
.

检查是否已安装：
```
which surgegraph-pp-cli
```
若未找到，提供安装选项（参见顶部前提条件）。
将用户查询与上方独特功能和命令参考中的最佳命令匹配。

添加

--agent

参数执行：

bash

surgegraph-pp-cli <command> [subcommand] [args] --agent

若存在歧义，查看子命令帮助：
```
surgegraph-pp-cli <command> --help
```
。