⌨️Ligne de commande

Pingclair se présente comme un seul binaire, dont la ligne de commande suit la forme Unix habituelle :

pingclair <command> [<args…>]

Les chevrons marquent ce qui est obligatoire, les crochets ce qui est facultatif, et … une valeur répétable. Chaque commande répond à --help avec le texte même qui a servi à écrire cette page, et pingclair help <command> l’affiche aussi. Lancer le binaire sans commande affiche la liste.

L’installateur crée aussi un lien pc, donc chaque commande ci-dessous a une orthographe de deux lettres : pc validate, pc service reload, etc. Les deux sont le même programme ; pc est un lien symbolique, pas un second binaire.

🚩 Options globales

Option	Effet
-v, --verbose	Passe le niveau de journal à debug pour cette exécution. Acceptée avant ou après la commande.
-h, --help	Affiche l’aide de la commande à laquelle elle est attachée.
-V, --version	Affiche la version. Au niveau supérieur uniquement.

🧭 Les commandes en un coup d’œil

Commande	Effet
run	Exécute le serveur au premier plan.
reload	Applique une configuration modifiée par l’Admin API, et rapporte ce que le serveur en a pensé.
start	Démarre une copie détachée du serveur.
stop	Arrête un serveur en cours par l’Admin API.
completion	Affiche un script de complétion pour un shell.
environ	Affiche l’environnement que verra le serveur.
list-modules	Liste les modules compilés dans ce binaire.
build-info	Affiche les métadonnées de compilation, chaîne d’outils comprise.
manpage	Écrit les pages de manuel dans un répertoire.
storage-export	Déplace le magasin de certificats dans une archive tar.
storage-import	Restaure ce magasin depuis cette archive.
trust	Installe la racine de l’autorité interne dans le magasin de confiance du système.
untrust	La retire.
respond	Sert une réponse fixe, pour le développement.
reverse-proxy	Proxy vers un amont sans fichier de configuration.
file-server	Sert un répertoire sans fichier de configuration.
validate	Compile une configuration et dit ce qui ne va pas.
adapt	Affiche la forme JSON compilée d’un Pingclairfile.
fmt	Formate un Pingclairfile, ou montre ce que le formatage changerait.
hash-password	Produit un hachage de mot de passe pour basic_auth.
version	Affiche la version.
service	Pilote l’unité systemd installée.

pingclair run

Exécute le serveur au premier plan avec un document de configuration. Les journaux vont sur la sortie standard et l’erreur standard, et Ctrl-C arrête le serveur.

pingclair run [OPTIONS] [CONFIG]

Argument	Défaut	Effet
CONFIG	./Pingclairfile, puis ./Caddyfile	Fichier ou répertoire de configuration à charger.

Option	Effet
-r, --resume	Charge la configuration que l’Admin API a sauvegardée en dernier, comme caddy run --resume. Remplace CONFIG quand les deux sont présents.
-w, --watch	Surveille le fichier de configuration — mtime, interrogé une fois par seconde — et envoie le signal de rechargement au processus après chaque changement. Prévu pour le développement local, où une modification refusée se voit vite.

pingclair run --watch

Pour un serveur qui survit au terminal, utilisez l’unité installée (Exécution comme service) ou Démarrage rapide, qui déroule la même commande en service.

pingclair reload

Applique une configuration modifiée à un serveur en cours par l’Admin API. Comme c’est le serveur qui répond à la requête, cette commande rapporte ce qu’il a pensé du fichier — contrairement à un signal, dont systemd peut seulement confirmer qu’il a été délivré.

pingclair reload [OPTIONS]

Option	Défaut	Effet
-c, --config <CONFIG>	./Pingclairfile, puis ./Caddyfile	Fichier de configuration à appliquer.
--address <ADDRESS>	127.0.0.1:2019	Adresse de l’Admin API.

L’Admin API doit tourner : l’option globale admin l’active, et une configuration sans cette option n’a aucun point de terminaison à joindre. Un rechargement que le serveur en cours ne peut pas appliquer — un changement de topologie d’écouteurs est le cas courant — laisse la configuration précédente en service.

sudo pingclair reload -c /etc/Pingclair/Pingclairfile

pingclair start

Démarre une copie du serveur qui continue après la fermeture du shell, sans gestionnaire de services.

pingclair start [OPTIONS]

Option	Défaut	Effet
-c, --config <CONFIG>	./Pingclairfile, puis ./Caddyfile	Fichier de configuration à charger.

Le processus est détaché du terminal et sa sortie est jetée, donc rien n’est journalisé nulle part. Sur un hôte avec systemd, l’unité installée est le meilleur outil : elle capture le journal, redémarre en cas d’échec et sait quand les écouteurs sont liés. Voir Exécution comme service.

pingclair stop

Arrête un serveur en cours par l’Admin API — le même POST /stop que l’Admin API expose. Exige l’option admin, comme reload.

pingclair stop [OPTIONS]

Option	Défaut	Effet
--address <ADDRESS>	127.0.0.1:2019	Adresse de l’Admin API.

pingclair completion

Affiche un script de complétion pour un shell. Les noms acceptés sont exactement ceux que prend l’argument : bash, zsh, fish, powershell, elvish.

pingclair completion <SHELL>

pingclair completion zsh > ~/.zfunc/_pingclair

pingclair environ

Affiche l’environnement avec lequel le serveur s’exécutera, pour vérifier une valeur telle que PINGCLAIR_TLS_STORE avant un démarrage plutôt que de la déduire d’un échec après coup.

pingclair environ

pingclair list-modules

Liste les modules et fonctions compilés dans ce binaire. --json affiche la même liste en sortie structurée, pour les scripts.

pingclair list-modules [--json]

pingclair build-info

Affiche les métadonnées de compilation : version, cible et chaîne d’outils qui a produit le binaire. Utile pour rapporter un défaut, car cela nomme la compilation exacte.

pingclair build-info

pingclair manpage

Écrit les pages de manuel dans un répertoire qui doit déjà exister. L’option est obligatoire, donc rien ne s’écrit dans le répertoire courant par accident.

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

pingclair storage-export

Écrit le magasin de certificats nommé par PINGCLAIR_TLS_STORE dans une archive tar. - comme chemin de sortie écrit l’archive sur la sortie standard.

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

L’archive contient des clés privées : elle est écrite en mode 600 et appartient à un support chiffré, pas à une sauvegarde qui part dans un bucket. Le guide TLS décrit ce qu’elle transporte et quand la déplacer.

pingclair storage-import

Restaure un magasin depuis une archive écrite par storage-export. - lit l’archive sur l’entrée standard.

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

pingclair trust

Installe la racine de l’autorité interne dans le magasin de confiance du système, après quoi les navigateurs et les clients en ligne de commande acceptent les certificats que cette autorité émet. La racine est lue depuis le magasin nommé par PINGCLAIR_TLS_STORE.

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

La page HTTPS décrit quand c’est nécessaire et comment vérifier que cela a fonctionné.

pingclair untrust

Retire cette racine du magasin de confiance du système. Les certificats déjà émis gardent leurs fichiers ; les clients cessent de leur faire confiance.

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

pingclair respond

Sert une réponse fixe — statut, en-têtes, corps — pour le développement et pour tester des clients contre une origine qui répond toujours de la même façon.

pingclair respond [OPTIONS]

Option	Défaut	Effet
-s, --status <STATUS>	200	Code de statut à renvoyer.
-H, --header <HEADERS>	aucun	En-tête de réponse au format Field: value. Répétable.
-b, --body <BODY>	vide	Corps de la réponse.
-l, --listen <LISTEN>	un port de boucle locale aléatoire	Adresse d’écoute.

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

Sans --listen, le port est choisi pour vous et affiché, ce qui évite que deux serveurs de développement se disputent un port fixe.

pingclair reverse-proxy

Démarre un proxy d’un écouteur vers un ou plusieurs amonts sans écrire de fichier de configuration. C’est la version en une ligne du guide du reverse proxy, et elle sert une configuration de forme production plutôt qu’un jouet : l’amont est obligatoire, et plusieurs valeurs --to répartissent la charge.

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

Option	Défaut	Effet
--from <FROM>	localhost	Adresse d’écoute.
--to <TO>	obligatoire	Adresse amont. Répétable pour en avoir plusieurs.
--header-up <HEADERS_UP>	aucun	En-tête de requête à envoyer en amont, au format Field: value. Répétable.
--header-down <HEADERS_DOWN>	aucun	En-tête de réponse à envoyer en aval, au format Field: value. Répétable.
--insecure	désactivé	Ignore la vérification TLS quand le certificat de l’amont ne correspond pas.
--internal-certs	désactivé	Émet les certificats de cet écouteur depuis l’autorité interne au lieu d’en demander un public.
--disable-redirects	désactivé	Ne provisionne pas l’écouteur de redirection HTTP vers HTTPS.
-c, --change-host-header	désactivé	Réécrit l’en-tête Host de l’amont avec l’adresse de l’amont, comme Caddy.

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

pingclair file-server

Sert un répertoire en HTTP sans fichier de configuration.

pingclair file-server [OPTIONS]

Option	Défaut	Effet
--listen <LISTEN>	:80	Adresse d’écoute.
--root <ROOT>	.	Répertoire à servir.
-b, --browse	désactivé	Affiche les listes de répertoire.
-d, --domain <DOMAIN>	aucun	Sert ce domaine en HTTPS ; exige que --listen soit un port.
--access-log	désactivé	Écrit une ligne d’accès par requête.
--no-compress	désactivé	Désactive la compression des réponses.
--file-limit <FILE_LIMIT>	aucun	Nombre maximal de fichiers affichés dans une liste de répertoire.
--templates	désactivé	Traite les fichiers .html comme des gabarits, comme Caddy.

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

La compression, les en-têtes de cache et les replis d’application monopage relèvent d’un fichier de configuration : le guide du site statique les couvre.

pingclair validate

Compile une configuration et rapporte le premier problème trouvé, sans rien démarrer. Le code de sortie est non nul quand la configuration est refusée, ce qui la rend utilisable dans un pipeline ou un script de déploiement.

pingclair validate [/etc/Pingclair/Pingclairfile]

Argument	Défaut	Effet
CONFIG	./Pingclairfile, puis ./Caddyfile	Fichier ou répertoire de configuration à vérifier.

sudo pingclair validate /etc/Pingclair/Pingclairfile

pingclair adapt

Affiche la forme JSON dans laquelle la configuration se compile. --pretty l’indente pour la lecture, et --validate exécute les contrôles qui touchent au système de fichiers — chemins de certificats, par exemple — au lieu de la seule syntaxe.

pingclair adapt [OPTIONS]

Option	Défaut	Effet
-c, --config <CONFIG>	./Pingclairfile, puis ./Caddyfile	Fichier de configuration à lire.
-p, --pretty	désactivé	Indente le JSON.
--validate	désactivé	Valide aussi ce à quoi le document adapté fait référence.

pingclair adapt --pretty --validate

pingclair fmt

Formate un Pingclairfile et affiche le résultat. Sans chemin, il lit ./Pingclairfile ; - lit l’entrée standard.

pingclair fmt [OPTIONS] [PATH]

Option	Effet
-o, --overwrite	Réécrit le texte formaté dans le fichier au lieu de l’afficher.
-d, --diff	Affiche un diff visuel plutôt que le fichier formaté.

pingclair fmt --diff              # ce qui changerait
pingclair fmt --overwrite         # l'appliquer

pingclair hash-password

Produit un hachage de mot de passe pour la directive basic_auth. Le mot de passe est lu sur l’entrée standard quand --plaintext est omis, ce qui le garde hors de l’historique du shell.

pingclair hash-password [OPTIONS]

Option	Défaut	Effet
-p, --plaintext <PLAINTEXT>	lu sur l’entrée standard	Mot de passe à hacher.
--algorithm <ALGORITHM>	bcrypt	bcrypt ou argon2id.
--bcrypt-cost <COST>	14	Coût bcrypt, de 4 à 31. Plus haut est plus lent et plus fort.
--argon2id-time <TIME>	1	Itérations argon2id.
--argon2id-memory <MEMORY>	65536	Coût mémoire argon2id, en Kio.
--argon2id-threads <THREADS>	4	Parallélisme argon2id.
--argon2id-keylen <KEYLEN>	32	Longueur de sortie argon2id, en octets.

pingclair hash-password --algorithm argon2id

Collez la sortie dans la directive ; l’entrée basic_auth montre la syntaxe autour.

pingclair version

Affiche la version, comme v0.2.0-rc.3 pour une version candidate.

pingclair version

pingclair service

Gère l’unité systemd écrite par l’installateur. C’est une enveloppe autour de systemctl, donc les deux sont interchangeables ; elle existe pour que les commandes de l’unité soient au même endroit que les autres.

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

Sous-commande	Effet
start	Démarre l’unité.
stop	Arrête l’unité.
restart	Redémarre l’unité, ce qu’exige un écouteur changé ou une option valable pour tout le processus.
reload	Demande au serveur en cours de relire son fichier de configuration, par signal. Le résultat est sur la ligne d’état de l’unité et dans le journal, pas dans le code de sortie de cette commande.
status	Affiche l’état de l’unité.

Linux avec systemd uniquement. Sur toute autre plateforme la commande refuse au lieu de faire semblant, et Exécution comme service est l’endroit où l’unité elle-même est documentée.

🧾 D’où viennent ces options

La ligne de commande est définie dans un seul fichier du code du serveur, pingclair/src/cli/mod.rs, et la page ci-dessus suit son ordre. La version affichée par chaque écran --help et la version contre laquelle cette page a été vérifiée sont la même ; quand les options d’une commande changent, cette page change avec elles.