HeaderKit CLI

HeaderKit 浏览器扩展的功能完整的命令行客户端。它连接运行中的扩展，让你或Agent在终端里创建、读取和修改 HeaderKit 的配置。

安装

npm install -g headerkit
# 或者不安装直接运行：
npx headerkit

使用

1. 启动 CLI：

headerkit                 # 启动 CLI，等待扩展配对
headerkit --help          # 打印完整命令参考并退出
headerkit --json          # 面向 agent 的机器模式（见下文）

2. 在 HeaderKit 扩展弹窗中，点击底部工具栏的 Connect CLI 按钮进行配对。在你点击 之前，CLI 会不断提醒你，命令也不会执行；配对成功后 CLI 会打印 ✓ Extension connected.。可以运行 status 查看状态。
3. 在 headerkit> 提示符后逐行输入命令。

只有 Origin 为浏览器扩展（chrome-extension:// 或 moz-extension://）的连接才会被 接受，因此探测你 localhost 的网页无法驱动它。已打包、未打包和开发版构建都无需任何额外 参数即可配对。

命令

profile create [name]                 profile list | get <id>
profile rename <id> <name>            profile color <id> <#hex>
profile enable|disable|delete <id>

rule add <pid> request-header <h> <v> [--action set|append|remove]
rule add <pid> response-header <h> <v> [--action ...]
rule add <pid> cookie <request|response> <name> <v> [--action ...]
rule add <pid> redirect <target> [--regex]
rule set <pid> <rid> field=value ...  # 字段：action|header|value|name|target|enabled
rule enable|disable|remove <pid> <rid>

filter add <pid> <pattern> [--regex] [--exclude]
filter remove <pid> <index>
resource <pid> [--include a,b] [--exclude c,d]

tab set <pid> <tabId> [label]         tab clear <pid>
window set <pid> <winId> <t1,t2,..> [label]   window clear <pid>

pause on|off
export                                # 以多行 JSON 导出全部 Profile
import <json>                         # JSON 必须为单行、无空格

ID（profile-xxxx / rule-xxxx）来自 profile list / profile create / profile get 的输出——先获取它们，再传给后续命令。含空格的值需要加引号： profile create "My Profile"。注意 import 需要单行 JSON，所以 export 的输出不能 直接粘贴回去。

内置命令：tabs 和 windows 列出当前浏览器的标签页 / 窗口（附带你在 tab set / window set 中要用的 id）；以及 status、help、exit。

Agent / 机器模式（--json）

使用 --json 启动可以以编程方式驱动 CLI。此时每行 stdout 都是一个 JSON 对象，且 headerkit> 提示符会被隐藏，因此你可以逐行解析输出流：

• 命令回复：{"ok":true,"result":...} 或 {"ok":false,"error":"..."}。 profile create / rule add 会把新 id 放在 result 中；profile list 返回一个 JSON 数组（而不是 ●/○ 文本行）；大多数编辑操作返回 result: null。
• 配对状态以事件形式到达： {"event":"listening","paired":false,"message":"Open the HeaderKit extension popup and click \"Connect CLI\" to pair."}， 然后在用户点击 Connect CLI 后变为 {"event":"paired"}。unpaired 和 waiting_for_pairing 事件也会携带同样的可操作 message。在发送命令前请先等待 paired，否则会收到 {"ok":false,"error":"Not paired yet …"}。

改动会立即生效：CLI 通过扩展写入 chrome.storage.local，随后会像你在界面里编辑一样 重新协调（reconcile）declarativeNetRequest 规则。

开发

npm install
npm run dev     # 从源码运行
npm run build   # 打包到 dist/index.js

CLI 复用了扩展自身在 ../src/core 中的 Profile 模型和命令语法，因此二者永远不会出现 偏差。