命令行

Pingclair 以一个二进制发布，命令行遵循 Unix 的惯例：

pingclair <command> [<args…>]

尖括号是必填，方括号是选填，… 表示可以重复。每个命令的 --help 返回的就是写这一页所用的同一份文本，pingclair help <command> 打印的也是它。不带命令运行会列出全部命令。

安装器还把二进制链接为 pc，所以下面每条命令都有两个字母的写法：pc validate、 pc service reload 等等。两者是同一个程序，pc 是符号链接，不是第二个二进制。

🚩 全局选项

选项	作用
`-v`, `--verbose`	把本次运行的日志级别提到 `debug`。放在命令前后都可以。
`-h`, `--help`	打印它所附着的那个命令的帮助。
`-V`, `--version`	打印版本。仅限顶层。

🧭 命令一览

命令	作用
`run`	在前台运行服务器。
`reload`	通过 Admin API 应用改过的配置，并报告服务器对它的判断。
`start`	启动一份脱离终端的服务器副本。
`stop`	通过 Admin API 停止正在运行的服务器。
`completion`	打印某个 shell 的补全脚本。
`environ`	打印服务器将看到的环境。
`list-modules`	列出编译进这个二进制的模块。
`build-info`	打印构建信息，包括工具链。
`manpage`	把 man 手册写进一个目录。
`storage-export`	把证书存储放进一个 tar 归档。
`storage-import`	从该归档恢复证书存储。
`trust`	把内部 CA 根证书装进系统信任存储。
`untrust`	再把它移除。
`respond`	开发时返回固定响应。
`reverse-proxy`	不写配置文件就代理到上游。
`file-server`	不写配置文件就提供目录。
`validate`	编译配置并说明哪里不对。
`adapt`	打印 Pingclairfile 编译出的 JSON。
`fmt`	格式化 Pingclairfile，或显示格式化会改动什么。
`hash-password`	为 `basic_auth` 生成密码哈希。
`version`	打印版本。
`service`	操作安装出来的 systemd unit。

pingclair run

用一份配置文档在前台运行服务器。日志走标准输出与标准错误，Ctrl-C 停止服务器。

pingclair run [OPTIONS] [CONFIG]

参数	默认	作用
`CONFIG`	`./Pingclairfile`，其次 `./Caddyfile`	要加载的配置文件或目录。

选项	作用
`-r`, `--resume`	像 `caddy run --resume` 那样，加载 Admin API 最后一次自动保存的配置。两者同时存在时覆盖 `CONFIG`。
`-w`, `--watch`	监视配置文件（每秒轮询 mtime），每次改动后给进程发重载信号。面向本地开发：被拒绝的编辑很快就能看见。

pingclair run --watch

要让服务器活过终端，请用安装出来的 unit（作为服务运行）或快速开始，后者把同一条命令按服务的方式讲一遍。

pingclair reload

通过 Admin API 把改过的配置应用到正在运行的服务器。应答请求的是服务器本身，所以这条命令会报告它对文件的判断——信号做不到这一点，systemd 只能确认信号已送达。

pingclair reload [OPTIONS]

选项	默认	作用
`-c`, `--config <CONFIG>`	`./Pingclairfile`，其次 `./Caddyfile`	要应用的配置文件。
`--address <ADDRESS>`	`127.0.0.1:2019`	Admin API 地址。

Admin API 必须开着：全局选项 admin 启用它，而没有该选项的配置没有任何端点可达。正在运行的服务器无法应用的重载——改动监听器拓扑是最常见的情形——会让旧配置继续服务。

sudo pingclair reload -c /etc/Pingclair/Pingclairfile

pingclair start

启动一份在 shell 退出后仍继续运行的服务器副本，不涉及服务管理器。

pingclair start [OPTIONS]

选项	默认	作用
`-c`, `--config <CONFIG>`	`./Pingclairfile`，其次 `./Caddyfile`	要加载的配置文件。

进程会脱离终端，输出被丢弃，因此任何地方都没有日志。在有 systemd 的主机上，安装出来的 unit 是更好的工具：它捕获日志、失败时重启，并且知道监听器何时绑定完成。见作为服务运行。

pingclair stop

通过 Admin API 停止正在运行的服务器——就是 Admin API 暴露的 POST /stop。和 reload 一样需要 admin 选项。

pingclair stop [OPTIONS]

选项	默认	作用
`--address <ADDRESS>`	`127.0.0.1:2019`	Admin API 地址。

pingclair completion

打印某个 shell 的补全脚本。可接受的名字与参数接受的完全一致：bash、zsh、 fish、powershell、elvish。

pingclair completion <SHELL>

pingclair completion zsh > ~/.zfunc/_pingclair

pingclair environ

打印服务器将要运行的环境，这样 PINGCLAIR_TLS_STORE 之类的值可以在启动前确认，而不是在启动后从失败里反推。

pingclair environ

pingclair list-modules

列出编译进这个二进制的模块与功能。--json 把同一份列表输出成结构化形式，供脚本使用。

pingclair list-modules [--json]

pingclair build-info

打印构建信息：版本、目标，以及产出这个二进制的工具链。报缺陷时有用，因为它指明了确切的构建。

pingclair build-info

pingclair manpage

把 man 手册写进一个必须已存在的目录。该选项是必填的，所以不会意外写进当前目录。

pingclair manpage --directory /usr/local/share/man/man1

pingclair storage-export

把 PINGCLAIR_TLS_STORE 指定的证书存储写进 tar 归档。输出路径写 - 则写到标准输出。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair \
  pingclair storage-export -o /tmp/store.tar

归档里有私钥，所以它以 600 权限写入，并且该放在加密介质上，而不是随备份进 bucket。TLS 指南说明了它装了什么、什么时候该搬。

pingclair storage-import

从 storage-export 写出的归档恢复存储。- 表示从标准输入读归档。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair \
  pingclair storage-import -i /tmp/store.tar

pingclair trust

把内部 CA 根证书装进系统信任存储，此后浏览器和命令行客户端都会接受该 CA 签发的证书。CA 从 PINGCLAIR_TLS_STORE 指定的存储里读取。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair trust

什么时候需要它、怎么确认生效，见 HTTPS。

pingclair untrust

再把这个根证书从系统信任存储移除。已经签发的证书文件还在，客户端不再信任它们。

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair untrust

pingclair respond

返回一个固定响应——状态、响应头、正文——用于开发和对着一个永远同样应答的上游测试客户端。

pingclair respond [OPTIONS]

选项	默认	作用
`-s`, `--status <STATUS>`	`200`	要返回的状态码。
`-H`, `--header <HEADERS>`	无	`Field: value` 形式的响应头。可重复。
`-b`, `--body <BODY>`	空	响应正文。
`-l`, `--listen <LISTEN>`	随机回环端口	监听地址。

pingclair respond --status 503 --header 'Retry-After: 30' --body 'down for maintenance'

不给 --listen 时端口由工具挑选并打印出来，这样两个开发服务器不会抢同一个固定端口。

pingclair reverse-proxy

不写配置文件，直接从监听地址代理到一个或多个上游。这是反向代理指南的一行版本，提供的是生产形态的配置而不是玩具：上游是必填的，多个 --to 会做负载均衡。

pingclair reverse-proxy [OPTIONS] --to <TO>

选项	默认	作用
`--from <FROM>`	`localhost`	监听地址。
`--to <TO>`	必填	上游地址。可重复指定多个。
`--header-up <HEADERS_UP>`	无	发往上游的请求头（`Field: value`）。可重复。
`--header-down <HEADERS_DOWN>`	无	发往下游的响应头（`Field: value`）。可重复。
`--insecure`	关	上游证书不匹配时跳过 TLS 校验。
`--internal-certs`	关	这个监听器的证书由内部 CA 签发，而不去申请公开证书。
`--disable-redirects`	关	不准备 HTTP 到 HTTPS 的重定向监听器。
`-c`, `--change-host-header`	关	像 Caddy 那样，把上游的 `Host` 头改写成上游地址。

pingclair reverse-proxy --from :8080 --to 127.0.0.1:3000

pingclair file-server

不写配置文件，直接把目录用 HTTP 提供出去。

pingclair file-server [OPTIONS]

选项	默认	作用
`--listen <LISTEN>`	`:80`	监听地址。
`--root <ROOT>`	`.`	要提供的目录。
`-b`, `--browse`	关	显示目录列表。
`-d`, `--domain <DOMAIN>`	无	用 HTTPS 提供这个域名；要求 `--listen` 是端口。
`--access-log`	关	每个请求写一行访问日志。
`--no-compress`	关	关闭响应压缩。
`--file-limit <FILE_LIMIT>`	无	目录列表里显示的文件数上限。
`--templates`	关	像 Caddy 那样把 `.html` 当模板渲染。

pingclair file-server --root ./public --browse --listen :8080

压缩、缓存头和单页应用回退属于配置文件，静态站点指南讲了这些。

pingclair validate

编译配置并报出第一个问题，什么都不启动。配置被拒绝时退出码非零，所以它能用在流水线或部署脚本里。

pingclair validate [/etc/Pingclair/Pingclairfile]

参数	默认	作用
`CONFIG`	`./Pingclairfile`，其次 `./Caddyfile`	要检查的配置文件或目录。

sudo pingclair validate /etc/Pingclair/Pingclairfile

pingclair adapt

打印配置编译出的 JSON 形式。--pretty 缩进便于阅读，--validate 会连需要动文件系统的检查——例如证书路径——一起跑，而不只是语法。

pingclair adapt [OPTIONS]

选项	默认	作用
`-c`, `--config <CONFIG>`	`./Pingclairfile`，其次 `./Caddyfile`	要读取的配置文件。
`-p`, `--pretty`	关	缩进 JSON。
`--validate`	关	同时校验转换后文档引用的东西。

pingclair adapt --pretty --validate

pingclair fmt

格式化 Pingclairfile 并打印结果。不给路径时读 ./Pingclairfile，- 读标准输入。

pingclair fmt [OPTIONS] [PATH]

选项	作用
`-o`, `--overwrite`	把格式化后的文本写回文件，而不是打印。
`-d`, `--diff`	打印可视化差异，而不是格式化后的文件。

pingclair fmt --diff              # 会改什么
pingclair fmt --overwrite         # 应用它

pingclair hash-password

为 basic_auth 指令生成密码哈希。省略 --plaintext 时从标准输入读密码，这样它不会留在 shell 历史里。

pingclair hash-password [OPTIONS]

选项	默认	作用
`-p`, `--plaintext <PLAINTEXT>`	从标准输入读	要哈希的密码。
`--algorithm <ALGORITHM>`	`bcrypt`	`bcrypt` 或 `argon2id`。
`--bcrypt-cost <COST>`	`14`	bcrypt 代价，4 到 31。越高越慢也越强。
`--argon2id-time <TIME>`	`1`	argon2id 迭代次数。
`--argon2id-memory <MEMORY>`	`65536`	argon2id 内存代价，单位 KiB。
`--argon2id-threads <THREADS>`	`4`	argon2id 并行度。
`--argon2id-keylen <KEYLEN>`	`32`	argon2id 输出长度，单位字节。

pingclair hash-password --algorithm argon2id

把输出贴进指令里；周边语法见 basic_auth。

pingclair version

打印版本，发布候选会像 v0.2.0-rc.3。

pingclair version

pingclair service

管理安装器写出的 systemd unit。它包装 systemctl，两者可以互换；存在的意义是让操作 unit 的命令和其余命令待在同一处。

pingclair service <start|stop|restart|reload|status>

子命令	作用
`start`	启动 unit。
`stop`	停止 unit。
`restart`	重启 unit，改动监听器或进程级选项后需要它。
`reload`	用信号请正在运行的服务器重新读取配置文件。结果在 unit 的 status line 和日志里，不在这条命令的退出码里。
`status`	打印 unit 状态。

仅限带 systemd 的 Linux。其他平台这条命令会直接拒绝而不是假装可以；unit 本身的说明在作为服务运行。

🧾 这些选项的出处

命令行定义在服务端源码的一个文件里，pingclair/src/cli/mod.rs，上面的页面按它的顺序排列。每个 --help 屏幕显示的版本与本页核对所用的版本是同一个；命令的选项变了，这一页也跟着变。

⌨️命令行