pp-substack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Substack — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

substack-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 substack --cli-only

Verify:
```
substack-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/media-and-entertainment/substack/cmd/substack-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.

Substack has no public API and the closed-source tools that work around it (WriteStack, StackSweller) stop at Notes scheduling and a heatmap. This CLI absorbs every endpoint the community has reverse-engineered across 8 wrappers, then transcends with local-SQLite analytics: per-Note subscriber attribution (

growth attribution

), engagement reciprocity tracking (

engage reciprocity

), and a goal-aware best-time recommender (

growth best-time

). Every command is MCP-callable so an agent can drive the full publish → engage → measure → swap loop.

本技能驱动

substack-pp-cli

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

通过Printing Press安装器安装：

bash

npx -y @mvanhorn/printing-press install substack --cli-only

验证安装：
```
substack-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/media-and-entertainment/substack/cmd/substack-pp-cli@latest

如果安装后执行

--version

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

$PATH

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

Substack没有公开API，而现有的闭源工具（如WriteStack、StackSweller）仅支持Notes排期和热度图功能。本CLI整合了社区通过8个包装器逆向工程得到的所有接口，并新增了本地SQLite分析功能：单条Note的订阅者归因（

growth attribution

）、互动互惠跟踪（

engage reciprocity

），以及基于目标的最佳发布时间推荐器（

growth best-time

）。所有命令都支持MCP调用，因此Agent可以驱动完整的发布→互动→衡量→互换循环。

When to Use This CLI

何时使用本CLI

Reach for this CLI when an agent needs to operate a Substack publication end-to-end: posting Notes on a cadence, drafting and publishing long-form, engaging with niche writers, finding swap partners, and measuring which content actually drove subs. It is the right pick over WriteStack/StackSweller when you need agent-native plumbing (--json, --select, --dry-run, typed exit codes), offline-first analytics (every join runs locally over SQLite), or coverage of the writer surface those tools don't expose.

当Agent需要端到端运营Substack出版物时，可使用本CLI：按节奏发布Notes、撰写并发布长文、与细分领域作者互动、寻找互换合作伙伴，以及衡量哪些内容真正带来了订阅用户。当你需要Agent原生管道（--json、--select、--dry-run、类型化退出码）、离线优先分析（所有关联操作在本地SQLite上运行），或覆盖其他工具未涉及的作者操作面时，本CLI是WriteStack/StackSweller的更佳选择。

Unique Capabilities

独特功能

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

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

Local state that compounds

可累积的本地状态

growth attribution
— Connect every Note you posted to the paid and free subscribers that actually arrived in the 24-hour window after, so you stop guessing which content drove growth.
Pick this over a generic stats call when an agent needs to decide which Note formats to repeat next week.
bash
```
substack-pp-cli growth attribution --days 30 --json --select rank,note_id,note_excerpt,subs_acquired,paid_subs_acquired
```
engage reciprocity
— See net-give/net-take per writer you engage with — who reciprocates your restacks/comments, who quietly free-rides on yours.
Use when an agent is deciding whether to keep investing in a swap partner; surfaces relationships before they go stale.
bash
```
substack-pp-cli engage reciprocity --days 30 --agent --select handle,outgoing,incoming,net,drift
```

growth attribution
— 将你发布的每条Note与发布后24小时内新增的付费和免费订阅用户关联起来，让你不再猜测哪些内容推动了增长。
当Agent需要决定下周重复使用哪种Note格式时，选择此命令而非通用统计调用。
bash
```
substack-pp-cli growth attribution --days 30 --json --select rank,note_id,note_excerpt,subs_acquired,paid_subs_acquired
```
engage reciprocity
— 查看你互动的每位作者的净贡献/净获取情况——谁会回推你的内容/评论，谁在默默蹭你的流量。
当Agent需要决定是否继续投入某个互换合作伙伴时使用此命令；它能在关系变僵前揭示真实的互动情况。
bash
```
substack-pp-cli engage reciprocity --days 30 --agent --select handle,outgoing,incoming,net,drift
```

Algorithm-aware automation

算法感知自动化

notes schedule --guard
— Refuse to fire (or queue) a Note that lands less than 30 minutes after your last own-Note or violates your time-of-day rotation. Returns typed exit 2 with a JSON diagnosis.
Stops an agent from accidentally torching its own reach by dumping a queue all at once.
bash
```
substack-pp-cli notes schedule --at 2026-05-10T13:00:00Z --body "hook line\n\nbody" --guard --json
```
growth best-time
— Top day-of-week × hour cells ranked for whichever growth signal you pick (paid subs, likes, restacks, or comments) — not a single average.
An agent picking when to schedule tomorrow's Notes can ask for the goal it's optimizing instead of guessing.
bash
```
substack-pp-cli growth best-time --days 90 --for-goal subs --json --select day_of_week,hour,rate,sample_size
```

notes schedule --guard
— 拒绝发布（或排队）距离上一条自发布Note不足30分钟，或违反你的时段轮换规则的Note。返回类型化退出码2及JSON诊断信息。
防止Agent一次性发布所有排队内容，意外损害自身曝光量。
bash
```
substack-pp-cli notes schedule --at 2026-05-10T13:00:00Z --body "hook line\n\nbody" --guard --json
```
growth best-time
— 根据你选择的增长指标（付费订阅、点赞、回推或评论），按星期×小时维度排名最佳发布时段——而非单一平均值。
Agent在安排次日Notes发布时间时，可以指定优化目标，无需猜测。
bash
```
substack-pp-cli growth best-time --days 90 --for-goal subs --json --select day_of_week,hour,rate,sample_size
```

Pattern intelligence

模式智能

discover patterns
— Mechanically extracts which hook patterns (curiosity-gap colon, 3-sentence formula, em-dash reframe, question opener) actually rank in a niche, with restack/comment ratios.
An agent drafting Notes can ask which hook shape currently outperforms in this niche before generating.
bash
```
substack-pp-cli discover patterns --niche productivity --sort restacks --since 14d --agent --select pattern,sample_count,avg_restacks,avg_comments,top_example
```
voice fingerprint
— Measurable voice profile — sentence length, em-dash rate, colon-hook rate, hook-line ratios, vocabulary uniqueness — for any handle, with --diff to compare against another writer.
An agent drafting Notes for a ghostwriter client can verify the output stays inside the client's voice envelope.
bash
```
substack-pp-cli voice fingerprint --handle maya --diff devon --json --select metric,self,other,delta
```

discover patterns
— 自动提取在细分领域中表现出色的标题钩子模式（好奇心缺口冒号、三句公式、破折号重构、问题开头），并附带回推/评论比率。
Agent在撰写Notes前，可以先了解当前细分领域中哪种钩子形式表现更好。
bash
```
substack-pp-cli discover patterns --niche productivity --sort restacks --since 14d --agent --select pattern,sample_count,avg_restacks,avg_comments,top_example
```
voice fingerprint
— 生成可量化的语音特征档案——句子长度、破折号使用率、冒号钩子率、钩子与正文比率、词汇独特性——支持对比另一位作者的特征（--diff参数）。
Agent为代笔客户撰写Notes时，可以验证输出是否符合客户的语音风格范围。
bash
```
substack-pp-cli voice fingerprint --handle maya --diff devon --json --select metric,self,other,delta
```

Network leverage

网络杠杆

recs find-partners
— Score candidate publications for a Substack Recommendations swap by mutual-overlap density across followee + recommendation graphs.
An agent running a weekly cross-promo pass can rank candidates instead of pitching cold.
bash
```
substack-pp-cli recs find-partners --my-pub on --top 20 --json --select rank,handle,pub,overlap_score,shared_followees
```
growth pod
— Given a list of handles, render a member × member engagement matrix — last 30 days of restacks/comments/likes between every pair.
An agent organizing a mutual-aid pod can see who's net-positive vs free-riding without a spreadsheet.
bash
```
substack-pp-cli growth pod --members maya,devon,priya,jordan --days 30 --json
```

recs find-partners
— 根据关注者+推荐图谱的互重叠密度，为Substack推荐互换候选出版物打分。
Agent在每周交叉推广时，可以对候选者进行排名，而非盲目投递。
bash
```
substack-pp-cli recs find-partners --my-pub on --top 20 --json --select rank,handle,pub,overlap_score,shared_followees
```
growth pod
— 给定作者列表，生成成员间的互动矩阵——过去30天内每对成员之间的回推/评论/点赞情况。
Agent组织互助小组时，无需电子表格即可查看谁是净贡献者、谁在蹭流量。
bash
```
substack-pp-cli growth pod --members maya,devon,priya,jordan --days 30 --json
```

Command Reference

命令参考

categories — Site-wide Substack category list — culture, technology, food, etc.

```
substack-pp-cli categories list
```
— List all Substack categories

substack-pp-cli categories list-publications

— List publications in a category

comments — Long-form post comments (distinct from Notes)

```
substack-pp-cli comments get
```
— Get a single comment by ID (same shape as a Note — Substack treats them uniformly)
```
substack-pp-cli comments list
```
— List comments on a post

discover — Discovery surfaces — search publications, embed metadata

```
substack-pp-cli discover
```
— Search Substack publications by query

drafts — Drafts CRUD + publish + schedule

```
substack-pp-cli drafts create
```
— Create a new draft
```
substack-pp-cli drafts delete
```
— Delete a draft
```
substack-pp-cli drafts get
```
— Get a draft by ID
```
substack-pp-cli drafts list
```
— List drafts
```
substack-pp-cli drafts prepublish
```
— Validate a draft for publication; returns blockers
```
substack-pp-cli drafts publish
```
— Publish a draft now
```
substack-pp-cli drafts schedule
```
— Schedule a draft for future publish (or unschedule with --post-date null)
```
substack-pp-cli drafts update
```
— Update an existing draft

feed — RSS feed for a publication

```
substack-pp-cli feed
```
— RSS XML feed (returns XML; use
```
--raw
```
to dump)

images — Image upload (data-URI JSON, not multipart)

```
substack-pp-cli images
```
— Upload an image; returns CDN URL. Body is data-URI JSON.

inbox — Authenticated reader feed (home feed) — Notes + posts surfaced for the current user

```
substack-pp-cli inbox home
```
— Authenticated home feed
```
substack-pp-cli inbox reader-posts
```
— Posts feed for current user

notes — Substack Notes — short-form posts (Substack treats Notes as comments internally)

```
substack-pp-cli notes new
```
— Post a new Note from Markdown (auto-converts to ProseMirror; the agent-friendly entry point)
```
substack-pp-cli notes create
```
— Post a new Note with raw ProseMirror JSON via
```
--body-json
```
```
substack-pp-cli notes schedule
```
— Schedule a Note locally with a cadence guard (refuses bursts within 30 min; typed exit 2)
```
substack-pp-cli notes get
```
— Get a single Note by ID
```
substack-pp-cli notes list-by-profile
```
— List Notes by a profile (cursor pagination)
```
substack-pp-cli notes reply
```
— Reply to an existing Note (parent_id + ProseMirror body)

posts — Long-form posts and archives on a specific publication

```
substack-pp-cli posts archive
```
— Public archive of a publication's posts
```
substack-pp-cli posts get-by-slug
```
— Get a published post by URL slug
```
substack-pp-cli posts list-published
```
— List published posts on the publication (auth required)
```
substack-pp-cli posts ranked-authors
```
— Ranked list of authors for a publication

profiles — Substack profiles — your own and other writers'

```
substack-pp-cli profiles from-linkedin
```
— Look up a Substack profile from a LinkedIn handle
```
substack-pp-cli profiles get-by-handle
```
— Get a public profile by handle (e.g. mvanhorn)
```
substack-pp-cli profiles get-by-id
```
— Get a public profile by numeric user ID
```
substack-pp-cli profiles handle-options
```
— Available handle suggestions for the current user
```
substack-pp-cli profiles posts
```
— All posts by an author across publications
```
substack-pp-cli profiles self
```
— Get the authenticated user's profile

recommendations — Substack Recommendations — outbound (publications I recommend)

```
substack-pp-cli recommendations <publication_id>
```
— List the publications a publication recommends

sections — Sections of a publication (newsletters can have multiple)

```
substack-pp-cli sections
```
— List sections + subscriptions

settings — Account settings + connectivity probe (used by doctor)

```
substack-pp-cli settings get
```
— Get account settings
```
substack-pp-cli settings ping
```
— Connectivity probe (non-destructive PUT used by doctor)

subs — Subscriber count + publication metadata

```
substack-pp-cli subs authors
```
— List bylined authors of a publication
```
substack-pp-cli subs count
```
— Get subscriber count (read off the launch-checklist payload)

tags — Post tags

```
substack-pp-cli tags create
```
— Create a new tag
```
substack-pp-cli tags list
```
— List all tags for the publication

categories — Substack全站分类列表——文化、科技、美食等。

```
substack-pp-cli categories list
```
— 列出所有Substack分类

substack-pp-cli categories list-publications

— 列出指定分类下的出版物

comments — 长文评论（与Notes不同）

```
substack-pp-cli comments get
```
— 通过ID获取单条评论（格式与Note相同——Substack统一处理它们）
```
substack-pp-cli comments list
```
— 列出某篇文章的评论

discover — 发现功能——搜索出版物、嵌入元数据

```
substack-pp-cli discover
```
— 通过关键词搜索Substack出版物

drafts — 草稿的增删改查+发布+排期

```
substack-pp-cli drafts create
```
— 创建新草稿
```
substack-pp-cli drafts delete
```
— 删除草稿
```
substack-pp-cli drafts get
```
— 通过ID获取草稿
```
substack-pp-cli drafts list
```
— 列出所有草稿
```
substack-pp-cli drafts prepublish
```
— 验证草稿是否可发布；返回阻碍因素
```
substack-pp-cli drafts publish
```
— 立即发布草稿
```
substack-pp-cli drafts schedule
```
— 排期草稿在未来发布（使用--post-date null取消排期）
```
substack-pp-cli drafts update
```
— 更新现有草稿

feed — 出版物的RSS订阅源

```
substack-pp-cli feed
```
— 获取RSS XML订阅源（返回XML；使用
```
--raw
```
直接输出）

images — 图片上传（使用data-URI JSON，而非多部分表单）

```
substack-pp-cli images
```
— 上传图片；返回CDN链接。请求体为data-URI JSON格式。

inbox — 已认证读者的订阅源（主页订阅源）——当前用户可见的Notes+文章

```
substack-pp-cli inbox home
```
— 获取已认证用户的主页订阅源
```
substack-pp-cli inbox reader-posts
```
— 获取当前用户的文章订阅源

notes — Substack Notes——短内容（Substack内部将Notes视为评论）

```
substack-pp-cli notes new
```
— 通过Markdown发布新Note（自动转换为ProseMirror格式；Agent友好的入口）
```
substack-pp-cli notes create
```
— 通过
```
--body-json
```
参数传入原始ProseMirror JSON发布新Note
```
substack-pp-cli notes schedule
```
— 本地排期Note，并附带节奏防护（拒绝30分钟内的密集发布；返回类型化退出码2）
```
substack-pp-cli notes get
```
— 通过ID获取单条Note
```
substack-pp-cli notes list-by-profile
```
— 通过作者主页列出Notes（游标分页）
```
substack-pp-cli notes reply
```
— 回复现有Note（需要parent_id + ProseMirror格式内容）

posts — 指定出版物的长文和归档

```
substack-pp-cli posts archive
```
— 出版物的公开文章归档
```
substack-pp-cli posts get-by-slug
```
— 通过URL别名获取已发布文章
```
substack-pp-cli posts list-published
```
— 列出出版物的已发布文章（需要认证）
```
substack-pp-cli posts ranked-authors
```
— 列出出版物的作者排名

profiles — Substack主页——你自己和其他作者的主页

```
substack-pp-cli profiles from-linkedin
```
— 通过LinkedIn用户名查找Substack主页
```
substack-pp-cli profiles get-by-handle
```
— 通过用户名获取公开主页（例如mvanhorn）
```
substack-pp-cli profiles get-by-id
```
— 通过数字用户ID获取公开主页
```
substack-pp-cli profiles handle-options
```
— 获取当前用户可用的用户名建议
```
substack-pp-cli profiles posts
```
— 获取某作者在所有出版物上的文章
```
substack-pp-cli profiles self
```
— 获取已认证用户的主页

recommendations — Substack推荐——向外推荐（我推荐的出版物）

substack-pp-cli recommendations <publication_id>

— 列出某出版物推荐的其他出版物

sections — 出版物的栏目（通讯可以有多个栏目）

```
substack-pp-cli sections
```
— 列出栏目+订阅情况

settings — 账户设置+连接探测（供doctor命令使用）

```
substack-pp-cli settings get
```
— 获取账户设置
```
substack-pp-cli settings ping
```
— 连接探测（doctor命令使用的非破坏性PUT请求）

subs — 订阅者数量+出版物元数据

```
substack-pp-cli subs authors
```
— 列出出版物的署名作者
```
substack-pp-cli subs count
```
— 获取订阅者数量（从启动检查列表负载中读取）

tags — 文章标签

```
substack-pp-cli tags create
```
— 创建新标签
```
substack-pp-cli tags list
```
— 列出出版物的所有标签

Freshness Contract

新鲜度协议

This printed CLI owns bounded freshness only for registered store-backed read command paths. In

--data-source auto

mode, those paths check

sync_state

and may run a bounded refresh before reading local data.

--data-source local

never refreshes.

--data-source live

reads the API and does not mutate the local store. Set

SUBSTACK_NO_AUTO_REFRESH=1

to skip the freshness hook without changing source selection.

Covered paths:

```
substack-pp-cli categories
```
```
substack-pp-cli categories list
```

substack-pp-cli categories list-publications

```
substack-pp-cli drafts
```
```
substack-pp-cli drafts create
```
```
substack-pp-cli drafts delete
```
```
substack-pp-cli drafts get
```
```
substack-pp-cli drafts list
```
```
substack-pp-cli drafts prepublish
```
```
substack-pp-cli drafts publish
```
```
substack-pp-cli drafts schedule
```
```
substack-pp-cli drafts update
```
```
substack-pp-cli inbox
```
```
substack-pp-cli inbox home
```
```
substack-pp-cli inbox reader-posts
```
```
substack-pp-cli inbox-posts
```
```
substack-pp-cli posts
```
```
substack-pp-cli posts archive
```
```
substack-pp-cli posts get-by-slug
```
```
substack-pp-cli posts list-published
```
```
substack-pp-cli posts ranked-authors
```
```
substack-pp-cli posts-published
```
```
substack-pp-cli posts-ranked
```
```
substack-pp-cli profiles
```
```
substack-pp-cli profiles from-linkedin
```
```
substack-pp-cli profiles get-by-handle
```
```
substack-pp-cli profiles get-by-id
```
```
substack-pp-cli profiles handle-options
```
```
substack-pp-cli profiles posts
```
```
substack-pp-cli profiles self
```
```
substack-pp-cli sections
```
```
substack-pp-cli subs
```
```
substack-pp-cli subs authors
```
```
substack-pp-cli subs count
```
```
substack-pp-cli tags
```
```
substack-pp-cli tags create
```
```
substack-pp-cli tags list
```

When JSON output uses the generated provenance envelope, freshness metadata appears at

meta.freshness

. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment.

本CLI仅对已注册的存储支持型读取命令路径提供有限的新鲜度保证。在

--data-source auto

模式下，这些路径会检查

sync_state

，并可能在读取本地数据前进行有限刷新。

--data-source local

模式从不刷新。

--data-source live

模式直接读取API，且不修改本地存储。设置

SUBSTACK_NO_AUTO_REFRESH=1

可跳过新鲜度钩子，无需更改数据源选择。

受支持的路径：

```
substack-pp-cli categories
```
```
substack-pp-cli categories list
```

substack-pp-cli categories list-publications

```
substack-pp-cli drafts
```
```
substack-pp-cli drafts create
```
```
substack-pp-cli drafts delete
```
```
substack-pp-cli drafts get
```
```
substack-pp-cli drafts list
```
```
substack-pp-cli drafts prepublish
```
```
substack-pp-cli drafts publish
```
```
substack-pp-cli drafts schedule
```
```
substack-pp-cli drafts update
```
```
substack-pp-cli inbox
```
```
substack-pp-cli inbox home
```
```
substack-pp-cli inbox reader-posts
```
```
substack-pp-cli inbox-posts
```
```
substack-pp-cli posts
```
```
substack-pp-cli posts archive
```
```
substack-pp-cli posts get-by-slug
```
```
substack-pp-cli posts list-published
```
```
substack-pp-cli posts ranked-authors
```
```
substack-pp-cli posts-published
```
```
substack-pp-cli posts-ranked
```
```
substack-pp-cli profiles
```
```
substack-pp-cli profiles from-linkedin
```
```
substack-pp-cli profiles get-by-handle
```
```
substack-pp-cli profiles get-by-id
```
```
substack-pp-cli profiles handle-options
```
```
substack-pp-cli profiles posts
```
```
substack-pp-cli profiles self
```
```
substack-pp-cli sections
```
```
substack-pp-cli subs
```
```
substack-pp-cli subs authors
```
```
substack-pp-cli subs count
```
```
substack-pp-cli tags
```
```
substack-pp-cli tags create
```
```
substack-pp-cli tags list
```

当JSON输出使用生成的来源信封时，新鲜度元数据会出现在

meta.freshness

字段中。将其视为受支持命令路径的当前缓存新鲜度，而非完整历史回填或API特定增强的保证。

Finding the right command

查找正确的命令

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

bash

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

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

which

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

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

表示没有确定的匹配项——请改用

--help

或更精确的查询。

Recipes

使用示例

Daily growth-loop morning ritual

每日增长循环晨间流程

bash

substack-pp-cli growth attribution --days 7 --agent --select rank,note_excerpt,subs_acquired

Syncs the last 24 hours, surfaces yesterday's Note→sub winners, and shows reciprocity drift before you start engaging.

bash

substack-pp-cli growth attribution --days 7 --agent --select rank,note_excerpt,subs_acquired

同步过去24小时的数据，展示昨日带来订阅用户的优质Note，并在你开始互动前显示互惠变化情况。

Batch-schedule a week of Notes with cadence guard

批量排期一周的Notes并启用节奏防护

bash

substack-pp-cli notes schedule --at 2030-05-13T09:00:00Z --body 'Tuesday hook line' --guard --json

Prints every scheduled Note's request without firing; --guard rejects sub-30-min spacing. Drop --dry-run to commit.

bash

substack-pp-cli notes schedule --at 2030-05-13T09:00:00Z --body 'Tuesday hook line' --guard --json

输出所有排期Note的请求但不发布；--guard参数会拒绝间隔小于30分钟的排期。移除--dry-run参数即可提交排期。

Find this week's swap partners and draft outreach

查找本周的互换合作伙伴并撰写 outreach 内容

bash

substack-pp-cli recs find-partners --my-pub on --top 5 --json --select rank,handle,pub,overlap_score

Ranks candidates by audience overlap, pipes the top 5 into the outreach drafter.

bash

substack-pp-cli recs find-partners --my-pub on --top 5 --json --select rank,handle,pub,overlap_score

根据受众重叠度对候选者排名，将前5名传入 outreach 撰写工具。

Voice-match a draft to a client (ghostwriter)

让草稿匹配客户的语音风格（代笔场景）

bash

substack-pp-cli voice fingerprint --handle alice --diff bob --json

Captures the client's measured voice profile as JSON, feeds it into Note generation; no LLM coupling — uses your own ANTHROPIC_API_KEY/OPENAI_API_KEY.

bash

substack-pp-cli voice fingerprint --handle alice --diff bob --json

捕获客户的可量化语音特征档案为JSON格式，供Note生成使用；无需耦合LLM——使用你自己的ANTHROPIC_API_KEY/OPENAI_API_KEY。

Surface deeply nested Note metadata with --select

使用--select提取深层嵌套的Note元数据

bash

substack-pp-cli notes get c-12345 --agent --select id,body,attachments.url,attachments.image_url,attachments.published_bylines.name,attachments.published_bylines.handle,context.users.name

Notes responses are deeply nested (attachments, bylines, contextual users). Dotted --select narrows the payload so an agent doesn't burn context parsing 30KB of JSON it doesn't need.

bash

substack-pp-cli notes get c-12345 --agent --select id,body,attachments.url,attachments.image_url,attachments.published_bylines.name,attachments.published_bylines.handle,context.users.name

Note的响应结构深度嵌套（附件、署名、上下文用户）。使用点分隔的--select参数可缩小返回 payload，避免Agent解析不需要的30KB JSON数据浪费上下文。

Auth Setup

认证设置

Substack uses a session cookie (substack.sid). The only path today is

auth login --chrome

(also accepts

--browser

as an alias) — it reads the cookie from your logged-in Chrome via pycookiecheat / cookies / cookie-scoop-cli and stores it in the OS keyring. There is no password login and no manual cookie-paste subcommand. If your cookie expires, re-run

auth login --chrome

Run

substack-pp-cli doctor

to verify setup.

Substack使用会话cookie（substack.sid）。目前唯一的认证方式是

auth login --chrome

（也接受

--browser

作为别名）——它通过pycookiecheat/cookies/cookie-scoop-cli从你已登录的Chrome中读取cookie，并存储到系统密钥环中。不支持密码登录和手动粘贴cookie的子命令。如果cookie过期，请重新运行

auth login --chrome

。

运行

substack-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
```
substack-pp-cli categories list --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
Explicit retries — use
```
--idempotent
```
only when an already-existing create should count as success, and
```
--ignore-missing
```
only when a missing delete target should count as success

在任何命令后添加

--agent

参数。它等效于：

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

。

可管道化 — 标准输出为JSON，错误信息输出到标准错误
可过滤 —
```
--select
```
参数保留字段子集。点路径可深入嵌套结构；数组会遍历每个元素。对于冗长的API，这是缩小上下文的关键：
bash
```
substack-pp-cli categories list --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求但不发送
离线友好 — 同步/搜索命令在可用时可使用本地SQLite存储
非交互式 — 从不提示，所有输入均通过标志参数提供
显式重试 — 仅当已存在的创建操作应视为成功时使用
```
--idempotent
```
参数；仅当缺失的删除目标应视为成功时使用
```
--ignore-missing
```
参数

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

字段表示数据是实时的还是本地的。仅当标准输出为终端时，才会向标准错误输出人类可读的

N results (live)

摘要；管道/Agent消费者仅会在标准输出获取纯JSON。

Agent Feedback

Agent反馈

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

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

Entries are stored locally at

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

. They are never POSTed unless

SUBSTACK_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

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

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

反馈条目存储在本地

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

文件中。除非设置了

SUBSTACK_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置了

SUBSTACK_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（ `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.

substack-pp-cli profile save briefing --json
substack-pp-cli --profile briefing categories list
substack-pp-cli profile list --json
substack-pp-cli profile show briefing
substack-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”模式。

substack-pp-cli profile save briefing --json
substack-pp-cli --profile briefing categories list
substack-pp-cli profile list --json
substack-pp-cli profile show briefing
substack-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
```
substack-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
→ 显示
```
substack-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 substack-pp-mcp -- substack-pp-mcp

Verify:

claude mcp list

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

bash

claude mcp add substack-pp-mcp -- substack-pp-mcp

验证安装：

claude mcp list

Direct Use

直接使用

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

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

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

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

带

--agent

标志执行命令：

bash

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

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