---
title: "CLI"
summary: "Server startup, version output, login links, health probes and offline repair."
description: "Commands and flags accepted by the Pitot binary."
status: preview
read_when:
  - "You need to run or script a Pitot command."
---
## 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](/docs/reference/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:

```sh
pitot login-link admin@example.com
# For Docker:
docker exec pitot pitot login-link admin@example.com
```

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](/docs/concepts/authentication#recover-local-sign-in).

### Break-glass links

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

```sh
pitot login-link --break-glass admin@example.com
```

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](/docs/concepts/authentication#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](/docs/guides/tls#require-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](/docs/guides/troubleshooting#an-unreadable-telemetry-batch-blocks-startup).

## 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. |