CLI

Commands and flags

Invocation	Behavior
pitot	Validate environment settings and start the server.
pitot version	Print the build version to stdout and exit.
pitot --version, pitot -v	Print the build version to stdout and exit.
pitot -h, pitot --help	Print usage to stderr and exit successfully.
pitot login-link <email>	Mint a login URL for an existing active local user.
pitot login-link --break-glass <email>	Mint a one-time login URL for an active administrator in OIDC mode.
pitot healthcheck [url]	Probe an explicit URL, or derive /healthz from listener settings.
pitot repair verify	Validate every authoritative telemetry batch without changing it.
pitot repair quarantine --batch <id>	Move one confirmed corrupt batch aside. --batch is required.

These are the complete subcommands and flags. Configuration comes from the environment, not CLI configuration flags. See configuration. Version output uses the release version embedded at build time, or dev when no version was embedded.

Login links

Run with the server’s environment and data directory:

pitot login-link [email protected]
# For Docker:
docker exec pitot pitot login-link [email protected]

The command requires local auth mode, an existing control database and an active user. It prints one URL to stderr. The URL expires in 15 minutes and works once. It can run while the server is online. See account recovery.

Break-glass links

Use --break-glass when an OIDC installation’s identity provider is unavailable:

pitot login-link --break-glass [email protected]

The flag requires OIDC auth mode, PITOT_AUTH_CODE_SECRET with at least 32 characters, and an active administrator. Other roles are refused. The URL expires in 15 minutes and works once. Without the flag the command refuses OIDC mode. See OIDC break-glass recovery.

Health probes

With no URL, healthcheck reads only PITOT_ADDR, PITOT_TLS_CERT_FILE, PITOT_HEALTHCHECK_CERT_FILE and PITOT_HEALTHCHECK_KEY_FILE. Unspecified bind hosts become 127.0.0.1. A certificate selects HTTPS. Derived probes bypass environment proxies; HTTPS IP probes trust the configured certificate and verify its first DNS or IP SAN. Hostname probes use normal verification. Derived HTTPS probes present the healthcheck client certificate when one is configured, for a listener that requires client certificates.

An explicit URL uses normal proxy and certificate verification. Each probe has a three-second timeout and succeeds only on HTTP 200. No auth secret is needed.

Offline repair

Stop Pitot and back up telemetry before running repair. Both commands load and validate the normal environment configuration. Verification reports each confirmed unreadable batch on stdout. An unsupported format or operational failure stops verification and does not authorize quarantine.

Quarantine renames one corrupt batch beside the authoritative set. It refuses a healthy batch or a batch protected by a compaction marker. Its rows become unavailable to queries. Preserve the reported destination for recovery, verify again, then restart. See batch recovery.

Exit status

Status	Meaning
0	Command completed successfully, including help and version.
1	Configuration or runtime failure, failed login-link creation, failed health probe, or repair failure. Verification finding corrupt batches also exits 1.
2	Invalid arguments or failure to derive the healthcheck address.