# 命令行

> 使用 proxyman-cli 在终端中控制 Proxyman for macOS：导出和导入规则、切换工具与系统代理、导出日志并管理证书。

Proxyman for macOS 自带 `proxyman-cli`，这是一个命令行工具，可用于在终端和你自己的脚本中控制 Proxyman ✅。

该工具位于 `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli`。

要查看当前已安装版本的全部命令，请运行：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli --help
```

## 1. 导出 Proxyman 配置 {#1-export-proxyman-config}

导出所有调试工具的规则，例如 SSL Proxying List、Breakpoint、Map Local、Scripting、Block List、Allow List、Reverse Proxy 和 Network Conditions。

```bash
$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -h

OVERVIEW: Export all debugging tools rules (Breakpoint, SSL Pinning, Map Local, Map
Remote, Scripting, etc).

USAGE: proxyman-cli export [--mode <mode>] --output <output>

OPTIONS:
  -m, --mode <mode>       Export Mode (all = "All debugging tools's rules", enabledRules
                          = "Only enabled rules"). (default: all)
  -o, --output <output>   A Output file to save the config to.
  --version               Show the version.
  -h, --help              Show help information.
```

> **备注:** 默认情况下，`export` 命令会导出所有规则。如需排除特定规则，请取消勾选各调试工具中的 “Enabled” 列，并使用 `-m enabledRules`

### 示例： {#for-example}

* 导出所有调试工具规则：

`$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -o ~/Desktop/data.json`

* 仅导出已启用的规则：

`$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli export -m enabledRules -o ~/Desktop/data.json`

## 2. 导入 Proxyman 配置 {#2-import-proxyman-config}

导入之前通过 export 命令导出的 Proxyman 调试工具规则。

```bash
$ /Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -h

OVERVIEW: Import config to Proxyman.

USAGE: proxyman-cli import [--mode <mode>] --input <input>

OPTIONS:
  -m, --mode <mode>       Import Mode (append = "Append to the existing rules"),
                          override = "Import and Replace all existing rules". (default:
                          append)
  -i, --input <input>     A input file to import.
  --version               Show the version.
  -h, --help              Show help information.
```

> **备注:** 默认情况下，导入的新规则会追加到现有的调试规则中。如需覆盖所有规则，请使用 `-m override`

### 示例： {#for-example-1}

* 以追加方式导入所有调试规则：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -i ~/Desktop/data.json
```

* 导入，但覆盖所有现有规则：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli import -m override -i ~/Desktop/data.json
```

## 3. 激活/解绑许可证 {#3-activateunlink-license}

激活和解绑许可证的命令，请参阅许可证页面。

- [Proxyman 许可证](https://proxyman.com/docs/zh-cn/license)

## 4. 切换 HTTP 系统代理 {#4-toggle-http-system-proxy}

从 Proxyman 4.8.0 版本开始，可以通过命令行开启或关闭 macOS 系统代理。[Raycast 扩展](https://proxyman.com/docs/zh-cn/raycast)即通过此命令实现。

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy on
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy off
```

参考：[https://github.com/ProxymanApp/Proxyman/issues/1626#issuecomment-1545862020](https://github.com/ProxymanApp/Proxyman/issues/1626#issuecomment-1545862020)

## 5. 清除会话 {#5-clear-session}

* 可通过命令行清除当前会话。Proxyman 4.12.0 及更高版本可用。

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli clear-session
```

## 6. 切换调试工具 {#6-toggle-debugging-tools}

* 通过命令行切换 Breakpoint、Map Local 和 Scripting 工具。Proxyman 4.12.0 及更高版本可用。

```bash
# Scripting
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli scripting on
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli scripting off

# Map Local
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli maplocal on
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli maplocal off

# Breakpoint
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli breakpoint on
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli breakpoint off
```

* 从 Proxyman macOS 6.3.0 版本开始，还可以用同样的方式切换以下工具：`map-remote`、`block-list`、`allow-list`、`reverse-proxy`、`network-condition`、`no-caching` 和 `dns-spoofing`。
* 使用 `open` 代替 `on` 或 `off` 可打开工具窗口，例如 `proxyman-cli map-remote open`。`no-caching` 仅支持 `on` 和 `off`。
* 运行这些命令时，Proxyman 必须处于运行状态。

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli map-remote on
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli block-list off
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-condition open
```

## 7. 通过命令行安装代理辅助工具 {#7-install-the-proxy-helper-tool-by-command-line}

从 Proxyman macOS 4.12.0 版本开始，无需图形界面即可安装辅助工具。

```bash
sudo /Applications/Proxyman.app/Contents/MacOS/proxyman --install-privileged-components
```

## 8. 导出 Proxyman 日志 {#8-export-proxyman-log}

**Proxyman macOS v5.11.0+ 现已支持：**

* 导出全部（ProxymanSession 格式）

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output"
```

* 导出指定域名（仅填写主机名，不含协议、端口、路径和查询字符串）

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com'
```

**从 Proxyman macOS 5.20.0+ 起，可导出为 Raw 或 HAR 格式。**

* 导出全部 - RAW 请求/响应格式

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output" --format raw
```

* 导出全部 - HAR 格式

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m all -o "~/desktop/output" --format har
```

* 导出指定域名 - RAW 请求/响应格式

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com' --format raw
```

* 导出指定域名 - HAR 格式

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli export-log -m domains -o "~/desktop/output" --domains 'api.twitter.com' --domains 'www.producthunt.com' --format har
```

**从 Proxyman macOS 6.2.0+ 起，可添加 `--since <flow_id>`，仅导出从该 flow ID 开始的记录（包括该 ID 对应的记录）。该参数适用于所有导出格式。**

`--format` 支持的格式包括 `proxymansession`（默认）、`har` 和 `raw`。

## 9. 导入自定义根证书 {#9-import-custom-root-certificate}

* ✅ 将自定义 p12 根证书导入 Proxyman
* 自动在系统钥匙串中信任该证书（需要 sudo 权限）
* 自 Proxyman macOS 5.15.0 版本起可用

### 安装并信任 {#install-and-trust}

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli install-root-cert <certificate_path> --password <your_cert_password> --trust
```

### 仅安装，不信任（可能需要在钥匙串中手动信任） {#install-but-not-trust-you-might-need-to-trust-it-manually-in-the-keychain}

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli install-root-cert <certificate_path> --password <your_cert_password>
```

## 10. 导出当前 IP 和端口 {#10-export-current-ip-and-port}

* 自 Proxyman macOS 6.7.0 版本起可用
* 以 JSON 格式获取当前监听的 IP 和端口

<pre class="language-bash"><code class="lang-bash"><strong>/Applications/Proxyman.app/Contents/MacOS/proxyman-cli proxy-host
</strong></code></pre>

输出包含 `ip` 和 `port` 字段，例如 `{"ip":"192.168.1.10","port":9090}`。如果 Proxyman 仅监听 localhost，则 IP 为 `127.0.0.1`。

## 11. 添加、删除和替换自定义证书（客户端和服务器）  {#11-add-remove-replace-the-custom-certificates-client-and-server-}

* 自 Proxyman macOS 6.10.0 版本起可用 ✅
* 支持带密码的 P12 证书
* 对于客户端证书，`--port` 默认为 `443`

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert add server ~/Desktop/mycert.p12 --password 123

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert add client ~/Desktop/mycert.p12 --password 123 --host myserver.com --port 443

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert replace server ~/Desktop/mycert.p12 --password 123 --name mycert.p12

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert replace client ~/Desktop/mycert.p12 --password 123 --host myserver.com --port 443

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert remove server --name mycert.p12

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli custom-cert remove client --host myserver.com --port 443
```

## 12. External Proxy 命令行 {#12-external-proxy-cli}

* Proxyman macOS 6.12.0 及更高版本 ✅

### 启用 {#enable}

在不修改已保存配置的情况下启用 External Proxy：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable
```

* 启用并配置代理模式：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable http --host proxy.example.com --port 8080
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable https --host proxy.example.com --port 8443
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable socks --host proxy.example.com --port 1080
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy enable pac --url https://example.com/proxy.pac
```

### 禁用 {#disable}

完全禁用 External Proxy 功能：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable
```

* 仅禁用单一代理模式：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable http
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable https
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable socks
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy disable pac
```

### 打开设置 {#open-the-settings}

在 Proxyman 中打开 External Proxy 设置窗口：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli external-proxy open
```

## 13. 所有调试工具的增删改查 {#13-crud-for-all-debugging-tools}

> **提示:** 仅适用于 Proxyman macOS 6.14.0 及更高版本

### 支持的工具 {#supported-tools}

`block-list`、`allow-list`、`ssl-proxying`、`map-local`、`map-remote`、`breakpoint`、`scripting`、`network-condition`、`reverse-proxy`、`protobuf` 和 `dns-spoofing`。

### 常用命令 {#common-commands}

将 `<tool>` 替换为上述受支持的工具之一，并将 `<id>` 替换为通过 `list` 或 `get` 获取的规则 ID。

```bash
# Read rules
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> list
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> list --enabled true
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> get <id>

# Change one rule
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> update <id> --name "New name"
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> delete <id>

# Turn a whole tool on or off
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> enable
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> disable

# Turn one rule on or off
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> enable <id>
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> disable <id>
```

`enable <id>` 需要时也会同时开启对应工具。关闭工具不会改变各规则自身的启用设置。更新操作只会修改所传入的字段；删除操作会立即移除规则。

`map-local`、`map-remote`、`breakpoint` 和 `scripting` 还提供 `folders` 命令用于管理规则文件夹，它们的 `list` 和 `create` 命令均接受 `--folder <name or id>` 参数。运行 `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local folders --help` 查看相关选项。

### 创建规则 {#create-a-rule}

以下为最简的创建命令。可选参数可用于设置更多字段。运行 `/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules <tool> create --help` 查看全部参数。

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules block-list create https://ads.example.com/*
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules allow-list create https://api.example.com/*
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules ssl-proxying create '*.example.com' --list include
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local create https://api.example.com/* --path ./response.json
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-remote create https://old.example.com/* https://new.example.com/
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules breakpoint create https://api.example.com/* --phase both
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules scripting create https://api.example.com/* --script-file ./rule.js
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules network-condition create --profile 3g
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules reverse-proxy create https://upstream.example.com --local-port 8080
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules protobuf create https://api.example.com/* --request-type package.Request
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules dns-spoofing create example.com 127.0.0.1
```

规则的常用参数包括 `--name`、`--enabled true|false`、`--method`、`--match wildcard|regex`，以及工具支持时可用的 `--include-subpaths true|false`。名称为可选项。若省略可选值，Proxyman 将使用该工具的默认值。

### JSON 输入 {#json-input}

创建和更新时，可使用 `--input <file>` 传入 JSON 对象；使用 `--input -` 从标准输入读取 JSON。请勿将 `--input` 与字段参数混用。

```bash
printf '%s' '{"url":"https://api.example.com/*","name":"Local API","enabled":true}' \
  | /Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local create --input -

/Applications/Proxyman.app/Contents/MacOS/proxyman-cli rules map-local update <id> --input ./map-local-change.json
```

Proxyman 未运行时，命令会返回 JSON，其中 `ok` 为 `false`，错误代码为 `app_not_running`。输入错误的退出码为 `2`，其他错误的退出码为 `1`。

## 14. 企业策略 {#14-company-policy}

### MCP（Proxyman macOS 6.15.0+） {#mcp-proxyman-macos-6150}

* 即使 Proxyman 已关闭，也可以启用或禁用 [MCP](https://proxyman.com/docs/zh-cn/mcp) 功能
* 如果通过命令行禁用了 MCP，用户将无法在设置中重新启用

禁用 MCP 并锁定设置中的开关：

```
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli mcp off
```

启用 MCP 并解锁开关：

```
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli mcp on
```

## 15. HTTP 版本 {#15-http-version}

读取或修改全局 [HTTP/2](https://proxyman.com/docs/zh-cn/basic-features/http2) 策略。请保持 Proxyman 处于打开状态；即使 MCP 已禁用，这些命令仍可正常工作。

```bash
# Read the current policy
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version status

# Prefer HTTP/2, with HTTP/1.1 fallback
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version set prefer_http2

# Turn the HTTP/2 preference off
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version set http1_only
```

HTTP/2 默认关闭。修改策略会关闭当前活动的 HTTP、WebSocket 和 Server-Sent Events 连接，并刷新 Compose 客户端。再次设置当前策略不会关闭连接。

该策略并不能证明某个请求实际使用了哪种协议。请检查捕获到的请求及上游连接。使用 Network Extension 捕获时，即使设置为 `http1_only`，仅提供 `h2` 的客户端仍会保持 HTTP/2。

两个命令均返回 JSON。`status` 的结果包含 `httpVersionMode` 和 `http2Enabled`；`set` 的结果还包含 `previousMode` 和 `changed`。例如，从 HTTP/1 切换为 HTTP/2 优先时，返回结果如下：

```json
{
  "success": true,
  "data": {
    "httpVersionMode": "prefer_http2",
    "http2Enabled": true,
    "previousMode": "http1_only",
    "changed": true
  }
}
```

## 16. 管理 Network Extension {#16-network-extension}

通过命令行管理 [Network Extension](https://proxyman.com/docs/zh-cn/advanced-features/network-extension) 的安装与捕获。请保持 Proxyman 处于打开状态；无需启用 MCP。

> **备注:** Network Extension 需要直接下载版的 Proxyman 及 macOS 26 或更高版本。安装和捕获需要 Proxyman PRO。状态查询和卸载无需 PRO 即可使用。Setapp 不支持 Network Extension。

```bash
# Read installation and capture status without changing either
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension status

# Install or update the bundled extension without enabling capture
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension install

# Enable capture, installing the extension if necessary
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension enable

# Stop capture and keep the extension installed
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension disable

# Retry requested installation or capture after resolving an error
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension retry

# Stop capture and remove the extension and its saved network configurations
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension uninstall
```

`install` 在捕获已关闭时会保持关闭状态。`enable` 会启动捕获，并关闭基于辅助工具的系统代理。Network Extension 捕获开启时，无法启用系统代理。

`disable` 和 `uninstall` 会通过提供程序关闭现有连接，包括直接 TCP 连接。之后，系统代理将遵循 **Auto Override System Proxy Settings at Launch** 设置。

macOS 可能会要求批准或重启。请完成相应步骤，然后再次运行 `network-extension status`。命令成功仅表示请求已被接受，并不代表安装或捕获已完成。如果操作处于忙碌状态或超时，请先查看状态，再重复执行。

HTTPS 解密仍需要受信任的 Proxyman 证书以及匹配的 SSL Proxying 规则。请让客户端重新连接，以便捕获新建立的连接。

### 读取 JSON 状态 {#read-the-json-status}

| 字段 | 含义 |
| --- | --- |
| `supported` | 当前应用和 macOS 版本是否支持 Network Extension。不支持的主机会返回 `false`，并拒绝所有更改。 |
| `installed`, `installedBuild`, `bundledBuild` | macOS 报告的安装状态，以及随正在运行的应用一同打包的构建版本。 |
| `systemExtensionEnabled` | macOS 是否报告已安装的扩展已启用。 |
| `proAvailable` | Proxyman PRO 是否可用于安装和捕获。 |
| `captureEnabled` | 是否已请求开启捕获。 |
| `captureActive` | 提供程序是否已确认捕获会话。 |
| `state`, `message` | 应用当前状态及可读的说明。 |
| `operationPending` | 安装、移除或捕获启动是否正在进行中。 |
| `approvalRequired`, `restartRequired` | 是否需要批准或重启。 |
| `removalPending` | macOS 中是否仍有等待移除的扩展记录，包括应用重新启动后的情况。 |
| `systemProxyEnabled` | Proxyman 当前是否报告 macOS 系统代理已启用。 |

受支持的主机会在 `data` 下返回上述字段。`disable` 不会等待安装查询，因此其响应中的 `installed` 为 `null`。如需检查最新安装状态，请使用 `status`。

### JSON 输出与退出码 {#json-output-and-exit-codes}

`http-version` 和 `network-extension` 命令组返回的 JSON 响应包含 `success`；可用时包含 `data`，失败时包含 `error`。

* `0`：读取成功，或更改已被接受。请通过 Network Extension 状态确认是否已完成。
* `1`：命令执行失败、Proxyman 未运行或命令超时。
* `64`：命令行参数无效。解析错误和帮助信息均为纯文本。

通过以下命令检查已安装应用支持的语法：

```bash
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli http-version --help
/Applications/Proxyman.app/Contents/MacOS/proxyman-cli network-extension --help
```