pp-ahrefs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ahrefs — Printing Press CLI

Ahrefs — Printing Press CLI工具

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

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

Verify:
```
ahrefs-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/marketing/ahrefs/cmd/ahrefs-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.

本技能基于

ahrefs-pp-cli

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

通过Printing Press安装程序安装：

bash

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

验证：
```
ahrefs-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/marketing/ahrefs/cmd/ahrefs-pp-cli@latest

若安装后执行

--version

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

$PATH

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

When Not to Use This CLI

何时不应使用此CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

请勿针对需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求激活此CLI。该CLI仅提供用于查看、导出、同步和分析的只读命令。

Command Reference

命令参考

keywords-explorer — Keywords Explorer endpoints.

ahrefs-pp-cli keywords-explorer matching-terms

— Matching terms

ahrefs-pp-cli keywords-explorer overview

— Overview

ahrefs-pp-cli keywords-explorer related-terms

— Related terms

ahrefs-pp-cli keywords-explorer search-suggestions

— Search suggestions

ahrefs-pp-cli keywords-explorer volume-by-country

— Volume by country

ahrefs-pp-cli keywords-explorer volume-history

— Time-series. Volume history

public — Public endpoints.

```
ahrefs-pp-cli public crawler-ip-ranges
```
— Crawler IP ranges
```
ahrefs-pp-cli public crawler-ips
```
— Crawler IP addresses

rank-tracker — Rank Tracker endpoints.

ahrefs-pp-cli rank-tracker competitors-overview

— Competitors overview

```
ahrefs-pp-cli rank-tracker overview
```
— Overview

ahrefs-pp-cli rank-tracker serp-overview

— SERP Overview

serp-overview — Serp Overview endpoints.

```
ahrefs-pp-cli serp-overview
```
— SERP Overview

site-audit — Site Audit endpoints.

```
ahrefs-pp-cli site-audit issues
```
— Project Issues
```
ahrefs-pp-cli site-audit page-content
```
— Page content
```
ahrefs-pp-cli site-audit page-explorer
```
— Page explorer
```
ahrefs-pp-cli site-audit projects
```
— Project Health Scores

site-explorer — Site Explorer endpoints.

ahrefs-pp-cli site-explorer all-backlinks

— Backlinks

ahrefs-pp-cli site-explorer backlinks-stats

— Backlinks stats

ahrefs-pp-cli site-explorer broken-backlinks

— Broken Backlinks

ahrefs-pp-cli site-explorer domain-rating

— Point-in-time snapshot. Domain rating

ahrefs-pp-cli site-explorer domain-rating-history

— Time-series. Domain Rating history

```
ahrefs-pp-cli site-explorer metrics
```
— Point-in-time snapshot. Metrics

ahrefs-pp-cli site-explorer metrics-by-country

— Metrics by country

ahrefs-pp-cli site-explorer organic-competitors

— Organic competitors

ahrefs-pp-cli site-explorer organic-keywords

— Organic keywords

ahrefs-pp-cli site-explorer pages-by-traffic

— Pages by traffic

ahrefs-pp-cli site-explorer refdomains-history

— Time-series. Refdomains history

```
ahrefs-pp-cli site-explorer top-pages
```
— Top pages

subscription-info — Subscription Info endpoints.

```
ahrefs-pp-cli subscription-info
```
— Limits and usage

keywords-explorer — 关键词探索器端点。

ahrefs-pp-cli keywords-explorer matching-terms

— 匹配关键词

ahrefs-pp-cli keywords-explorer overview

— 概览

ahrefs-pp-cli keywords-explorer related-terms

— 相关关键词

ahrefs-pp-cli keywords-explorer search-suggestions

— 搜索建议

ahrefs-pp-cli keywords-explorer volume-by-country

— 各国搜索量

ahrefs-pp-cli keywords-explorer volume-history

— 时间序列搜索量历史

public — 公开端点。

```
ahrefs-pp-cli public crawler-ip-ranges
```
— 爬虫IP范围
```
ahrefs-pp-cli public crawler-ips
```
— 爬虫IP地址

rank-tracker — 排名追踪器端点。

ahrefs-pp-cli rank-tracker competitors-overview

— 竞品概览

```
ahrefs-pp-cli rank-tracker overview
```
— 概览

ahrefs-pp-cli rank-tracker serp-overview

— SERP概览

serp-overview — SERP概览端点。

```
ahrefs-pp-cli serp-overview
```
— SERP概览

site-audit — 站点审计端点。

```
ahrefs-pp-cli site-audit issues
```
— 项目问题
```
ahrefs-pp-cli site-audit page-content
```
— 页面内容
```
ahrefs-pp-cli site-audit page-explorer
```
— 页面探索器
```
ahrefs-pp-cli site-audit projects
```
— 项目健康评分

site-explorer — 站点探索器端点。

ahrefs-pp-cli site-explorer all-backlinks

— 全部反向链接

ahrefs-pp-cli site-explorer backlinks-stats

— 反向链接统计

ahrefs-pp-cli site-explorer broken-backlinks

— 失效反向链接

ahrefs-pp-cli site-explorer domain-rating

— 快照式域名评级

ahrefs-pp-cli site-explorer domain-rating-history

— 时间序列域名评级历史

```
ahrefs-pp-cli site-explorer metrics
```
— 快照式指标

ahrefs-pp-cli site-explorer metrics-by-country

— 各国指标

ahrefs-pp-cli site-explorer organic-competitors

— 自然搜索竞品

ahrefs-pp-cli site-explorer organic-keywords

— 自然搜索关键词

ahrefs-pp-cli site-explorer pages-by-traffic

— 按流量排序页面

ahrefs-pp-cli site-explorer refdomains-history

— 时间序列引用域名历史

```
ahrefs-pp-cli site-explorer top-pages
```
— 热门页面

subscription-info — 订阅信息端点。

```
ahrefs-pp-cli subscription-info
```
— 限制与使用情况

Finding the right command

查找合适的命令

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

bash

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

ahrefs-pp-cli which "<用您自己的语言描述功能>"

which

命令会将自然语言查询匹配到CLI功能索引中最合适的命令。退出码

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

表示无匹配结果，请改用

--help

或更精确的查询。

Auth Setup

身份验证设置

Set your API key via environment variable:

bash

export AHREFS_API_KEY="<your-key>"

Or persist it in

~/.config/ahrefs-pp-cli/config.toml

Run

ahrefs-pp-cli doctor

to verify setup.

通过环境变量设置API密钥：

bash

export AHREFS_API_KEY="<您的密钥>"

也可将密钥持久化存储在

~/.config/ahrefs-pp-cli/config.toml

中。

执行

ahrefs-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
```
ahrefs-pp-cli keywords-explorer matching-terms --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
Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests

在任意命令后添加

--agent

参数，等效于：

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

。

可管道传输 — 标准输出为JSON格式，错误信息输出到标准错误
可过滤 —
```
--select
```
参数保留指定字段。点路径可深入嵌套结构；数组会遍历每个元素。对于数据量大的API，此参数可有效精简返回内容：
bash
```
ahrefs-pp-cli keywords-explorer matching-terms --agent --select id,name,status
```
可预览 —
```
--dry-run
```
参数显示请求内容但不发送
离线友好 — 同步/搜索命令在本地SQLite存储可用时可使用本地数据
非交互式 — 从不弹出提示，所有输入均通过参数传递
只读 — 请勿使用此CLI执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他修改状态的请求

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": <数据>
}

解析

.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:

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

Entries are stored locally at

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

. They are never POSTed unless

AHREFS_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

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

ahrefs-pp-cli feedback "--since参数实际为包含性，但文档说明为排他性"
ahrefs-pp-cli feedback --stdin < notes.txt
ahrefs-pp-cli feedback list --json --limit 10

反馈条目会本地存储在

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

中。除非设置了

AHREFS_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置

AHREFS_FEEDBACK_AUTO_SEND=true

，否则反馈不会自动发送。默认仅本地存储。

请记录您感到意外的内容，而非正式的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.

ahrefs-pp-cli profile save briefing --json
ahrefs-pp-cli --profile briefing keywords-explorer matching-terms
ahrefs-pp-cli profile list --json
ahrefs-pp-cli profile show briefing
ahrefs-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"模式）。

ahrefs-pp-cli profile save briefing --json
ahrefs-pp-cli --profile briefing keywords-explorer matching-terms
ahrefs-pp-cli profile list --json
ahrefs-pp-cli profile show briefing
ahrefs-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
```
ahrefs-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
→ 显示
```
ahrefs-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/marketing/ahrefs/cmd/ahrefs-pp-mcp@latest

bash

claude mcp add ahrefs-pp-mcp -- ahrefs-pp-mcp

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

go install github.com/mvanhorn/printing-press-library/library/marketing/ahrefs/cmd/ahrefs-pp-mcp@latest

在Claude Code中注册：

bash

claude mcp add ahrefs-pp-mcp -- ahrefs-pp-mcp

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

Direct Use

直接使用

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

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

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

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

带

--agent

参数执行命令：

bash

ahrefs-pp-cli <命令> [子命令] [参数] --agent

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