pp-postman-explore

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Postman Explore — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

postman-explore-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 install postman-explore --cli-only

Verify:
```
postman-explore-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.23+):

bash

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-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.

本技能驱动

postman-explore-pp-cli

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

通过Printing Press安装程序安装：

bash

npx -y @mvanhorn/printing-press install postman-explore --cli-only

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

如果

npx

安装失败（无Node环境、离线等情况），可回退到直接通过Go安装（要求Go 1.23+版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-cli@latest

如果安装后执行

--version

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

$PATH

中。请在验证成功前不要执行本技能的命令。

When to Use This CLI

何时使用此CLI

Pick this CLI when you need to programmatically discover, compare, or watch community-contributed Postman Collections / workspaces / APIs / flows. Ideal for AI agents asked to find a canonical Postman Collection for a vendor, for API curators comparing publishers in a category, and for monitoring scripts that watch network changes. Skip this CLI for managing your own private Postman workspace — that's the authenticated Postman product API, which is a different surface entirely.

当您需要以编程方式发现、比较或监控社区贡献的Postman Collections/工作区/API/流程时，选择此CLI。非常适合需要为供应商查找标准Postman Collection的AI Agent、需要比较某一类别中发布者的API管理者，以及需要监控网络变化的脚本。如果您是管理自己的私有Postman工作区，请跳过此CLI——这属于需要认证的Postman产品API范畴，是完全不同的操作面。

Unique Capabilities

独特功能

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

这些功能是其他同类API工具所不具备的。

Discovery that compounds locally

本地聚合式发现

canonical
— One command finds the best community Postman Collection for a vendor, ranked by publisher verification, fork count, and recency.
When the user asks an agent for a vendor's Postman Collection, this returns the best canonical choice in one call instead of forcing the agent to dedupe a search result list.
bash
```
postman-explore-pp-cli canonical stripe --json
```
top
— Rank entities by any metric (weekForks, monthViewCount, etc.) with category and entity-type narrowing.
When agents need to recommend the most-forked collections THIS week, not the all-time leaders, this is the only path that works.
bash
```
postman-explore-pp-cli top --metric weekForkCount --type collection --category payments --limit 10
```
similar
— Given an entity numeric id, return collections with overlapping name, summary, and category — ranked by FTS relevance score against the seed entity's text.
When an integrator finds one collection but wants to compare against alternatives, this returns the rivals in one call rather than forcing a fresh search.
bash
```
postman-explore-pp-cli similar 10289 --limit 5 --json
```

canonical
—— 一条命令即可找到供应商对应的最佳社区Postman Collection，按发布者认证状态、派生次数和更新时间排序。
当用户向Agent询问供应商的Postman Collection时，此命令可直接返回最佳标准选项，无需Agent手动去重搜索结果列表。
bash
```
postman-explore-pp-cli canonical stripe --json
```
top
—— 按任意指标（weekForks、monthViewCount等）对实体进行排名，支持按类别和实体类型筛选。
当Agent需要推荐本周派生次数最多的集合（而非历史总榜）时，这是唯一可行的方式。
bash
```
postman-explore-pp-cli top --metric weekForkCount --type collection --category payments --limit 10
```
similar
—— 给定实体数字ID，返回名称、简介和类别重叠的集合，并按与种子实体文本的FTS相关性得分排序。
当集成者找到一个集合但想要对比替代选项时，此命令可直接返回同类竞品，无需重新搜索。
bash
```
postman-explore-pp-cli similar 10289 --limit 5 --json
```

Comparative analysis

对比分析

publishers top
— Aggregate fork counts across every entity per publisher within a category; rank teams by total community gravity.
API curators picking between vendors need cross-publisher comparison. Agents recommending an integration partner need this to break ties.
bash
```
postman-explore-pp-cli publishers top --category developer-productivity --limit 5 --json
```
category landscape
— For a category slug, return: total entity counts per type, top 5 publishers by aggregate fork count, and top 5 entities by viewCount. One command, one structured payload.
API curators evaluating a vertical (payments, AI, devops) want one snapshot of who dominates and what's popular; this is exactly that snapshot.
bash
```
postman-explore-pp-cli category landscape payments --json
```

publishers top
—— 聚合某一类别中每个发布者旗下所有实体的派生次数，按社区总影响力对团队进行排名。
API管理者在供应商之间做选择时需要跨发布者对比，Agent推荐集成合作伙伴时也需要此功能来打破平局。
bash
```
postman-explore-pp-cli publishers top --category developer-productivity --limit 5 --json
```
category landscape
—— 针对指定类别别名，返回：各类型实体总数、按聚合派生次数排名的前5位发布者、按浏览量排名的前5位实体。一条命令即可获取结构化的完整快照。
API管理者评估某一垂直领域（支付、AI、DevOps等）时，需要一份能展示主导者和热门内容的快照，此命令正好满足需求。
bash
```
postman-explore-pp-cli category landscape payments --json
```

Time-windowed signals

时间窗口信号

drift
— Compare two synced snapshots and report new entities, removed entities, and entities whose updatedAt advanced.
Agents tracking when a vendor publishes a new collection or updates an existing one rely on this; there is no other way to know.
bash
```
postman-explore-pp-cli drift --since 7d --type collection --json
```
velocity
— Rank collections by acceleration ratio: (weekForkCount × 4) / monthForkCount. Surfaces collections breaking out before they top the popular list.
Catching a breakout collection before it tops the popular sort is high-value for API curators tracking emerging vendors.
bash
```
postman-explore-pp-cli velocity --type collection --top 10
```

drift
—— 对比两个同步快照，报告新增实体、移除实体和更新时间有变化的实体。
Agent追踪供应商何时发布新集合或更新现有集合时依赖此功能，没有其他方式可以实现这一点。
bash
```
postman-explore-pp-cli drift --since 7d --type collection --json
```
velocity
—— 按加速比率对集合排名：(weekForkCount × 4) / monthForkCount。可在集合登上热门榜单前发现其爆发趋势。
对于追踪新兴供应商的API管理者来说，在集合登上热门排序前捕捉到其爆发趋势具有很高价值。
bash
```
postman-explore-pp-cli velocity --type collection --top 10
```

Quality signals

质量信号

browse
— When passed --verified-only, the browse command filters to entities owned by publishers with the verified-team flag set.
When you want only the official-vendor collections (not community forks), this is the cleanest filter.
bash
```
postman-explore-pp-cli browse collection --verified-only --category payments --json --limit 5
```

browse
—— 当传入
```
--verified-only
```
参数时，浏览命令会筛选出由带有verified-team标识的发布者所拥有的实体。
当您只需要官方供应商的集合（而非社区派生版本）时，这是最简洁的筛选方式。
bash
```
postman-explore-pp-cli browse collection --verified-only --category payments --json --limit 5
```

HTTP Transport

HTTP传输

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

此CLI使用兼容Chrome的HTTP传输来处理面向浏览器的端点。正常API调用不需要常驻浏览器进程。

Discovery Signals

发现信号

This CLI was generated with browser-observed traffic context.

Capture coverage: 17 API entries from 24 total network entries
Protocols: rest_json (60% confidence), rpc_envelope (95% confidence)
Auth signals: none
Generation hints: client_pattern:proxy-envelope, uses_browser_http_transport, no_auth_required, skip_clearance_cookie
Emitted command surface: browse; networkentity get-network-entity; networkentity get-network-entity-counts; category list-categories; category get; team get-workspaces; team get; search-all

此CLI是基于浏览器观测到的流量上下文生成的：

捕获覆盖率：24条网络条目里的17条API条目
协议：rest_json（60%置信度）、rpc_envelope（95%置信度）
认证信号：无
生成提示：client_pattern:proxy-envelope、uses_browser_http_transport、no_auth_required、skip_clearance_cookie
已实现命令面：browse; networkentity get-network-entity; networkentity get-network-entity-counts; category list-categories; category get; team get-workspaces; team get; search-all

Command Reference

命令参考

category — Manage category

postman-explore-pp-cli category get

— Returns full details for a category by its URL slug (e.g.,

artificial-intelligence

developer-productivity

,...

```
postman-explore-pp-cli category list-categories
```
— Returns all categories used to organize the API network (e.g., AI, E-commerce, Communication, DevOps). Categories...

networkentity — Manage networkentity

postman-explore-pp-cli networkentity get-network-entity

— Returns full entity record by internal numeric id (the

id

field from

listNetworkEntities

, NOT the

entityId

UUID).

```
postman-explore-pp-cli networkentity get-network-entity-counts
```
— Returns aggregate counts across the entire public API network: collections, workspaces, APIs, flows, notebooks,...
```
postman-explore-pp-cli networkentity list-network-entities
```
— List public collections, workspaces, APIs, or flows. Supports category filtering, pagination, and minimum-fork...

search-all — Manage search all

```
postman-explore-pp-cli search-all
```
— Search collections, workspaces, requests, flows, and teams by free-text query. With no
```
queryIndices
```
set, the...

team — Publisher teams on the API network

```
postman-explore-pp-cli team get
```
— Returns small profile object (id, name, description, publicHandle, profileURL, createdAt, updatedAt) for a team by...
```
postman-explore-pp-cli team get-workspaces
```
— Returns the array of public workspaces owned by a team identified by its
```
publicHandle
```
(e.g.,
```
stripedev
```
,...

category —— 管理类别

postman-explore-pp-cli category get

—— 通过URL别名返回类别的完整详情（例如：

artificial-intelligence

、

developer-productivity

等）

```
postman-explore-pp-cli category list-categories
```
—— 返回用于组织API网络的所有类别（例如：AI、电商、通信、DevOps等）。类别...

networkentity —— 管理网络实体

```
postman-explore-pp-cli networkentity get-network-entity
```
—— 通过内部数字ID返回完整实体记录（来自
```
listNetworkEntities
```
的
```
id
```
字段，而非
```
entityId
```
UUID）。
```
postman-explore-pp-cli networkentity get-network-entity-counts
```
—— 返回整个公共API网络的聚合统计：集合、工作区、API、流程、笔记本等的数量...
```
postman-explore-pp-cli networkentity list-network-entities
```
—— 列出公共集合、工作区、API或流程。支持类别筛选、分页和最小派生次数...

search-all —— 管理全局搜索

```
postman-explore-pp-cli search-all
```
—— 通过自由文本查询搜索集合、工作区、请求、流程和团队。如果未设置
```
queryIndices
```
，则...

team —— API网络上的发布者团队

```
postman-explore-pp-cli team get
```
—— 通过...返回团队的小型资料对象（id、名称、描述、publicHandle、profileURL、createdAt、updatedAt）
```
postman-explore-pp-cli team get-workspaces
```
—— 返回由
```
publicHandle
```
标识的团队所拥有的公共工作区数组（例如：
```
stripedev
```
等）...

Finding the right command

找到合适的命令

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

bash

postman-explore-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

postman-explore-pp-cli which "<用您自己的话描述功能>"

which

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

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

表示没有匹配项——请回退到

--help

或使用更具体的查询。

Recipes

使用示例

Find Stripe's official collection

查找Stripe的官方集合

bash

postman-explore-pp-cli canonical stripe --json --select id,name,publisher.publicHandle,metrics.forkCount

The canonical command picks the verified-publisher, highest-fork-count match and narrows the JSON to the four fields agents actually need.

bash

postman-explore-pp-cli canonical stripe --json --select id,name,publisher.publicHandle,metrics.forkCount

canonical命令会选择经过认证的发布者中派生次数最多的匹配项，并将JSON结果精简为Agent实际需要的四个字段。

Compare top payments publishers

对比顶级支付类发布者

bash

postman-explore-pp-cli publishers top --category payments --limit 5 --json

Aggregate fork counts across each publisher's full portfolio in the payments category.

bash

postman-explore-pp-cli publishers top --category payments --limit 5 --json

聚合支付类别中每个发布者全系列产品的派生次数。

What changed on the network this week

本周API网络有哪些变化

bash

postman-explore-pp-cli sync && postman-explore-pp-cli drift --since 7d --type collection --json

Sync, then diff against the previous snapshot to find newly added or recently updated collections.

bash

postman-explore-pp-cli sync && postman-explore-pp-cli drift --since 7d --type collection --json

先同步，再与之前的快照对比，找出新增或最近更新的集合。

Browse top developer-productivity collections, narrow to verified publishers

浏览顶级开发者生产力集合，仅显示认证发布者的内容

bash

postman-explore-pp-cli browse collection --category 4 --verified-only --limit 10 --json --select name,publisher.publicHandle,metrics.viewCount,redirectURL

Use --select with dotted paths to avoid pulling the full ~5 KB metric array per record — keeps output small for agent context.

bash

postman-explore-pp-cli browse collection --category 4 --verified-only --limit 10 --json --select name,publisher.publicHandle,metrics.viewCount,redirectURL

使用

--select

和点路径来避免每条记录都返回约5KB的指标数组——可缩小Agent上下文的输出内容。

Find accelerating collections in payments

查找支付领域中呈爆发趋势的集合

bash

postman-explore-pp-cli velocity --type collection --category payments --top 10

Velocity ranks by week-vs-month fork rate, surfacing collections that are breaking out before they top the all-time popular list.

bash

postman-explore-pp-cli velocity --type collection --category payments --top 10

Velocity按周/月派生比率排名，可在集合登上历史热门榜单前发现其爆发趋势。

Find collections similar to a seed

查找与种子集合相似的集合

bash

postman-explore-pp-cli similar 10289 --limit 5 --json

More-like-this query against the local FTS index — useful for discovering rival or complementary community collections.

bash

postman-explore-pp-cli similar 10289 --limit 5 --json

针对本地FTS索引执行“相似内容”查询——有助于发现同类竞品或互补的社区集合。

Get a category-wide snapshot

获取类别全景快照

bash

postman-explore-pp-cli category landscape payments --json

Combines per-type counts, top publishers, and top entities for a category in one structured payload.

bash

postman-explore-pp-cli category landscape payments --json

将某一类别的各类型实体数量、顶级发布者和顶级实体整合到一个结构化负载中。

Auth Setup

认证设置

No authentication required.

Run

postman-explore-pp-cli doctor

to verify setup.

无需认证。

运行

postman-explore-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
```
postman-explore-pp-cli category get mock-value --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Offline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数。等效于：

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

。

可管道传输 —— JSON输出到标准输出，错误信息输出到标准错误
可筛选 ——
```
--select
```
保留字段子集。点路径可深入嵌套结构；数组可遍历元素。对于冗长的API来说，这是缩小上下文的关键：
bash
```
postman-explore-pp-cli category get mock-value --agent --select id,name,status
```
可预览 ——
```
--dry-run
```
显示请求但不发送
离线友好 —— 同步/搜索命令可在本地SQLite存储可用时使用该存储
非交互式 —— 从不提示，所有输入均通过标志参数提供

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

从本地存储或API读取数据的命令会将输出包装在来源信封中：

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析

.results

获取数据，

.meta.source

可了解数据是来自实时API还是本地存储。仅当标准输出为终端时，才会将人类可读的

N results (live)

摘要打印到标准错误——管道/Agent消费者只会在标准输出获取纯JSON。

Agent Feedback

Agent反馈

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

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

Entries are stored locally at

~/.postman-explore-pp-cli/feedback.jsonl

. They are never POSTed unless

POSTMAN_EXPLORE_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

POSTMAN_EXPLORE_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存在问题时，可记录反馈：

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

反馈条目会存储在本地

~/.postman-explore-pp-cli/feedback.jsonl

文件中。除非设置了

POSTMAN_EXPLORE_FEEDBACK_ENDPOINT

且传入了

--send

参数或设置了

POSTMAN_EXPLORE_FEEDBACK_AUTO_SEND=true

，否则反馈不会被POST到服务器。默认行为仅存储在本地。

请写下让您感到意外的内容，而非正式的 bug 报告。简短、具体、一句话即可：这样的反馈才更有价值。

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（当使用 `--compact` 时为 `application/json` 或 `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.

postman-explore-pp-cli profile save briefing --json
postman-explore-pp-cli --profile briefing category get mock-value
postman-explore-pp-cli profile list --json
postman-explore-pp-cli profile show briefing
postman-explore-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”模式。

postman-explore-pp-cli profile save briefing --json
postman-explore-pp-cli --profile briefing category get mock-value
postman-explore-pp-cli profile list --json
postman-explore-pp-cli profile show briefing
postman-explore-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
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

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

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
postman-explore-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
→ 显示
```
postman-explore-pp-cli --help
```
输出
以
install
开头 → 结尾为
```
mcp
```
→ MCP安装；否则 → 参见上方前提条件部分
其他情况 → 直接使用（带
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-mcp@latest

bash

claude mcp add postman-explore-pp-mcp -- postman-explore-pp-mcp

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-mcp@latest

注册到Claude Code：

bash

claude mcp add postman-explore-pp-mcp -- postman-explore-pp-mcp

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which postman-explore-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

postman-explore-pp-cli <command> [subcommand] [args] --agent

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

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

带

--agent

参数执行：

bash

postman-explore-pp-cli <command> [subcommand] [args] --agent

如果存在歧义，查看子命令帮助：
```
postman-explore-pp-cli <command> --help
```
。