pp-archive-is

archive.today — Printing Press CLI

前提条件：安装 CLI

此技能使用 archive-is-pp-cli 二进制文件。**调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

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

2. 验证：archive-is-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/archive-is/cmd/archive-is-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功之前，请勿继续执行技能命令。

何时使用此 CLI

当用户想要存档某个 URL、阅读付费墙后的文章、查看某项内容是否曾被存档，或批量捕获一组 URL 以供研究时，请使用此 CLI。特别适用于以下情况：

• 用户发送了一个付费墙链接并询问“能帮我读一下吗” → read 通过存档获取文本
• 用户想保留一个可能发生变化的 URL → save 强制进行新的捕获
• 用户想查看历史版本 → history 列出所有已知快照
• 用户有 20 个以上的 URL 要存档 → bulk 执行限速批量存档

如果 URL 无需存档服务即可轻松抓取（没有付费墙、robots 允许抓取、HTTP 可直接访问），或用户想要的是原始来源而非缓存版本，请勿使用此 CLI。

独特功能

整个 CLI 都独具特色——archive.today 没有官方 API。不过，在此 CLI 中，有些命令尤其突出。

核心命令

• read <url> — 查找或创建某个 URL 的存档。首先查找现有快照（Memento timegate → CDX 回退）；仅当不存在快照时才提交新的捕获。这是一个“总能做对”的命令。

  90% 的 Agent 调用都应从此命令开始。它具有幂等性——对同一 URL 调用两次不会重复提交。

• get <url> [--raw] / tldr <url> — 获取文章文本，可选由大模型生成摘要。当 archive.today 返回 CAPTCHA 时（这种情况每天都会发生在云 IP 上），会自动回退到 Wayback。

  tldr 会将获取的文本传入摘要步骤——适用于需要简短总结、且不想将 20KB HTML 传回的 Agent 调用链。

持久性操作

• save <url> — 通过 /submit/?url=<x>&anyway=1 强制进行新的捕获。若 read 返回的现有快照过旧或未包含付费墙更新，可使用此命令。

• history <url> — 通过解析 Memento timemap 列出所有已知快照。显示 archive.today 和 Wayback 上的每个捕获日期。

• bulk [file] — 从文件或标准输入执行限速批量存档。每行读取一个 URL，逐个提交并采用退避策略，然后返回成功、失败和已存在项目的报告。

  grep -oE 'https?://[^ )]+' notes.md | archive-is-pp-cli bulk - 会存档 Markdown 文件中的每个 URL。

• request <url> — 提交请求后即返回，可选择等待并轮询。适用于耗时较长的捕获，方便稍后再查看结果。

可观测性

• snapshots newest <url> — 仅返回目标的最新快照 URL，适用于脚本。

• captures — 列出本地捕获索引（同步后）。

• feeds — archive.today 的全局近期存档信息流。

• --backend archive-is,wayback — 每个 read/get 命令都接受后端偏好设置。默认优先使用 archive-is，Wayback 作为回退；调整顺序即可优先使用 Wayback。

命令参考

存档与检索：

• archive-is-pp-cli read <url> — 查找或创建（核心命令）
• archive-is-pp-cli get <url> — 获取文章文本（失败时回退到 Wayback）
• archive-is-pp-cli tldr <url> — 获取并总结
• archive-is-pp-cli save <url> — 强制创建新快照
• archive-is-pp-cli request <url> — 提交后立即返回
• archive-is-pp-cli request check <url> — 检查已提交的请求是否已完成

列表与历史记录：

• archive-is-pp-cli history <url> — 所有已知快照
• archive-is-pp-cli snapshots <url> — URL 的最佳已知快照
• archive-is-pp-cli snapshots newest <url> — 最新快照的 URL
• archive-is-pp-cli snapshots timemap <url> — 原始 Memento timemap
• archive-is-pp-cli captures — 本地快照索引
• archive-is-pp-cli feeds — 全局最新动态

批量操作：

• archive-is-pp-cli bulk [file] — 从文件或标准输入批量处理

本地存储：

• archive-is-pp-cli sync / export / import / workflow archive — 本地 SQLite 操作

身份验证与健康检查：

• archive-is-pp-cli auth — 配置（无需 API 密钥；身份验证不执行任何操作）
• archive-is-pp-cli doctor — 验证后端是否可访问

使用示例

阅读付费墙后的文章

archive-is-pp-cli read "https://www.wsj.com/articles/..." --agent
# or: return just the text
archive-is-pp-cli get "https://www.wsj.com/articles/..." --agent

read 会返回存档 URL（查找现有存档或创建新存档）。默认情况下，get 会返回提取后的文章文本；如果 archive.today 出现 CAPTCHA，则会回退到 Wayback。仅在需要存档 HTML 时才添加 --raw。

在 URL 发生变化前保存

archive-is-pp-cli save "https://example.com/important-page" --agent
archive-is-pp-cli history "https://example.com/important-page" --agent  # verify

强制创建快照，然后检查历史记录，确认新快照已登记。

批量存档一批研究资料

grep -oE 'https?://[^ )]+' research-notes.md | archive-is-pp-cli bulk - --agent
# or from a file:
archive-is-pp-cli bulk urls.txt --agent

每行读取一个 URL，并通过指数退避机制逐一提交；以 JSON 格式返回每个 URL 的状态（已存档、已存在、失败）。

优先使用 Wayback 以确保可靠读取

archive-is-pp-cli read "https://ft.com/content/xyz" --backend wayback,archive-is --agent

如果已知 Wayback Machine 的快照更完整，或 archive.today 正在进行速率限制，请使用此选项。

身份验证设置

无需 API 密钥。 Archive.today 和 Wayback Machine 都是公共服务。auth 子命令是为保持一致性而提供的，但不执行任何操作；doctor 会报告“Auth: not required”，这就是预期状态。

可选环境变量：

• ARCHIVE_IS_BASE_URL — 覆盖 archive.today 主机（用于镜像站点）
• WAYBACK_BASE_URL — 覆盖 Wayback Machine 主机

Agent 模式

为任何命令添加 --agent。它会展开为 --json --compact --no-input --no-color --yes --no-prompt。以非交互方式调用时，每个操作命令还会在 stderr 上输出结构化的 next_actions 提示——调用方 Agent 会自动看到“尝试了 X，得到 Y，可考虑 Z”。

重要标志：

• --submit-timeout <duration> — 等待新提交的最长时间（默认值为 10m；0 = 不限时）
• --backend archive-is,wayback — 后端首选项及回退顺序
• --raw — get 返回原始 HTML，而非提取后的文本

筛选输出

--select 接受点分隔路径，用于深入访问嵌套响应；数组会逐元素遍历：

archive-is-pp-cli <command> --agent --select id,name
archive-is-pp-cli <command> --agent --select items.id,items.owner.name

使用此选项可将庞大的负载缩小到实际需要的字段——这对于深度嵌套的 API 响应尤其重要。

响应封装

数据层命令会将输出封装在 {"meta": {...}, "results": <data>} 中。解析 .results 获取数据，并查看 .meta.source 以确定数据来自 live 还是本地。仅当 stdout 是 TTY 时，N results (live) 摘要才会输出到 stderr；通过管道或由 Agent 消费时，stdout 只包含纯 JSON。

退出代码

代码	含义
0	成功
2	用法错误
3	未找到（不存在快照）
5	API 错误（archive.today 或 Wayback 无法访问）
7	受到速率限制（提交次数过多）

安装

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/archive-is/cmd/archive-is-pp-cli@latest
archive-is-pp-cli doctor

MCP 服务

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/archive-is/cmd/archive-is-pp-mcp@latest
claude mcp add archive-is-pp-mcp -- archive-is-pp-mcp

参数解析

给定 $ARGUMENTS：

1. 为空、help 或 --help → 运行 archive-is-pp-cli --help
2. install → CLI；install mcp → MCP
3. 任何看起来像 URL 的内容，或“archive ”/“bypass paywall on ” → 默认使用 read <url> --agent——此操作幂等，适用于 90% 的情况。
4. “bulk archive”/“archive these” → 如果粘贴了 URL，则从 stdin 使用 bulk；否则询问文件路径。

Agent 工作流功能

此 CLI 提供了三项共享的 Agent 工作流功能，这些功能回移自 cli-printing-press PR #218。

命名配置

将一组标志保存为指定名称，并在多次调用中重复使用。

# Save the current non-default flags as a named profile
archive-is-pp-cli profile save <name>

# Use a profile — overlays its values onto any flag you don't set explicitly
archive-is-pp-cli --profile <name> <command>

# List / inspect / remove
archive-is-pp-cli profile list
archive-is-pp-cli profile show <name>
archive-is-pp-cli profile delete <name> --yes

标志优先级：显式标志 > 环境变量 > 配置 > 默认值。

--deliver

将命令输出路由到 stdout 以外的目标。当 Agent 需要将结果传递到文件、webhook 或其他进程，而无需自行处理管道连接时，此功能非常有用。

archive-is-pp-cli <command> --deliver file:/path/to/out.json
archive-is-pp-cli <command> --deliver webhook:https://hooks.example/in

文件目标会以原子方式写入（临时文件 + 重命名）。Webhook 目标会 POST application/json（设置 --compact 时则使用 application/x-ndjson）。遇到未知协议时，会返回结构化拒绝信息，并列出受支持的协议。

feedback

记录 Agent 在此 CLI 交互过程中提供的反馈。默认仅保存在本地，无需配置即可安全调用。

archive-is-pp-cli feedback "what surprised you or tripped you up"
archive-is-pp-cli feedback list         # show local entries
archive-is-pp-cli feedback clear --yes  # wipe

条目会以 JSON 行的形式追加到 ~/.archive-is-pp-cli/feedback.jsonl。如果设置了 ARCHIVE_IS_FEEDBACK_ENDPOINT，且传入了 --send 或 ARCHIVE_IS_FEEDBACK_AUTO_SEND=true，条目还会 POST 到上游（不会阻塞——本地写入始终会成功）。