コマンドライン

Pingclair は単一のバイナリとして配布され、コマンドラインは Unix の慣例どおり次の形を取ります。

pingclair <command> [<args…>]

山かっこは必須、角かっこは任意、… は繰り返せる値を表します。どのコマンドも --help に、このページを書くときに使ったのと同じテキストを返し、 pingclair help <command> も同じものを表示します。コマンドなしで実行すると一覧が出ます。

インストーラはバイナリを pc としてもリンクするので、以下のコマンドにはすべて 2 文字の綴りがあります: pc validate、pc service reload など。どちらも同じプログラムで、pc はシンボリックリンクであり 2 つ目のバイナリではありません。

🚩 グローバルフラグ

フラグ	効果
`-v`, `--verbose`	この実行のログ水準を `debug` に上げます。コマンドの前後どちらでも受け付けます。
`-h`, `--help`	そのフラグが付いたコマンドのヘルプを表示します。
`-V`, `--version`	バージョンを表示します。トップレベル専用です。

🧭 コマンド一覧

コマンド	効果
`run`	サーバーをフォアグラウンドで実行します。
`reload`	編集した設定を Admin API 経由で適用し、サーバーがどう判断したかを報告します。
`start`	切り離されたサーバーのコピーを起動します。
`stop`	実行中のサーバーを Admin API 経由で停止します。
`completion`	シェルの補完スクリプトを出力します。
`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 ユニットを操作します。

pingclair run

1 つの設定ドキュメントでサーバーをフォアグラウンド実行します。ログは標準出力と標準エラーに流れ、Ctrl-C で停止します。

pingclair run [OPTIONS] [CONFIG]

引数	既定	効果
`CONFIG`	`./Pingclairfile`、次に `./Caddyfile`	読み込む設定ファイルまたはディレクトリ。

フラグ	効果
`-r`, `--resume`	`caddy run --resume` と同様に、Admin API が最後に自動保存した設定を読み込みます。両方ある場合は `CONFIG` を上書きします。
`-w`, `--watch`	設定ファイルを監視し（mtime を 1 秒ごとに確認）、変更のたびにプロセスへ再読み込み信号を送ります。ローカル開発向けで、拒否された編集がすぐ見えます。

pingclair run --watch

ターミナルより長く生きるサーバーには、導入されたユニット（サービスとして動かす）かクイックスタートを使ってください。後者は同じコマンドをサービスとして順に説明しています。

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

シェルが終了しても残るサーバーのコピーを、サービス管理機構なしで起動します。

pingclair start [OPTIONS]

フラグ	既定	効果
`-c`, `--config <CONFIG>`	`./Pingclairfile`、次に `./Caddyfile`	読み込む設定ファイル。

プロセスは端末から切り離され、出力は捨てられるので、どこにも記録が残りません。 systemd のあるホストでは導入されたユニットのほうが適しています。ログを捕まえ、失敗時に再起動し、リスナーがバインドされた時点を把握します。サービスとして動かすを参照してください。

pingclair stop

実行中のサーバーを Admin API 経由で停止します。Admin API が公開している POST /stop と同じです。reload と同様に admin オプションが必要です。

pingclair stop [OPTIONS]

フラグ	既定	効果
`--address <ADDRESS>`	`127.0.0.1:2019`	Admin API のアドレス。

pingclair completion

1 つのシェル向けの補完スクリプトを出力します。受け付ける名前は引数が取るものと同じです: 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 で書かれ、バケットへ送るバックアップではなく暗号化された媒体に置くべきものです。何を含むか、いつ移動するかは 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 は 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

設定ファイルを書かずに、待ち受けから 1 つ以上のアップストリームへのプロキシを起動します。リバースプロキシガイドの一行版で、おもちゃではなく本番の形をした設定を配信します。アップストリームは必須で、複数の --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 を省略するとパスワードは標準入力から読むので、シェルの履歴に残りません。

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 ユニットを操作します。systemctl のラッパーなのでどちらでも同じで、ユニット向けのコマンドを他と同じ場所に置くために存在します。

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

サブコマンド	効果
`start`	ユニットを起動します。
`stop`	ユニットを停止します。
`restart`	ユニットを再起動します。リスナーやプロセス全体のオプションを変えた場合はこれが必要です。
`reload`	実行中のサーバーに設定ファイルを読み直すよう信号で求めます。結果はユニットの status line とジャーナルにあり、このコマンドの終了コードにはありません。
`status`	ユニットの状態を表示します。

systemd のある Linux 専用です。それ以外のプラットフォームでは、このコマンドはふりをせず拒否します。ユニット自体の説明はサービスとして動かすにあります。

🧾 これらのオプションの出どころ

コマンドラインはサーバー側の 1 つのファイル pingclair/src/cli/mod.rs で定義され、上のページはその順序に従っています。各 --help に出るバージョンと、このページを突き合わせたバージョンは同じです。コマンドのフラグが変われば、このページも一緒に変わります。

⌨️コマンドライン