⌨️명령줄

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	셸 완성 스크립트를 출력합니다.
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

하나의 설정 문서로 서버를 포그라운드에서 실행합니다. 로그는 표준 출력과 표준 오류로 가고, 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

셸 하나를 위한 완성 스크립트를 출력합니다. 받아들이는 이름은 인수가 취하는 것과 정확히 같습니다: 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

설정 파일을 쓰지 않고 대기 주소에서 하나 이상의 업스트림으로 가는 프록시를 시작합니다. 리버스 프록시 가이드의 한 줄 버전이며, 장난감이 아니라 운영 형태의 설정을 제공합니다. 업스트림은 필수이고, 여러 --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

아무것도 시작하지 않고 설정을 컴파일해 첫 번째 문제를 보고합니다. 설정이 거부되면 종료 코드가 0이 아니므로 파이프라인이나 배포 스크립트에서도 쓸 수 있습니다.

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 전용입니다. 다른 플랫폼에서는 이 명령이 흉내 내지 않고 거부하며, 유닛 자체의 설명은 서비스로 실행에 있습니다.

🧾 이 옵션들의 출처

명령줄은 서버 코드의 한 파일 pingclair/src/cli/mod.rs에 정의되어 있고, 위 페이지는 그 순서를 따릅니다. 각 --help 화면에 나오는 버전과 이 페이지를 대조한 버전은 같습니다. 명령의 플래그가 바뀌면 이 페이지도 함께 바뀝니다.