# CLI reference

Four commands. Logs to stderr, results to stdout, non-zero exit on any failure.

```
gitdr <command> [flags]
```

Four commands. Structured logs go to stderr, machine-readable results go to stdout, and
the exit code is the contract: **0 means the whole run succeeded, anything else means
treat it as a failed backup.** No partial success reported as success, ever.

## Common flags (every command)

| Flag | Default | What |
|---|---|---|
| `--config` | `$GITDR_CONFIG` | path to the config YAML |
| `--output` | `text` | result format on stdout, `text` or `json` |
| `--log-level` | from config | `debug` `info` `warn` `error` |
| `--log-format` | from config | `json` or `text` |

## backup

Clone, bundle, checksum, upload create-only, sign the run-manifest.

```sh
gitdr backup --config config.yaml [--repo owner/name] [--require-worm]
```

| Flag | What |
|---|---|
| `--repo` | back up one repo, overrides `source.repo` |
| `--require-worm` | fail closed if the destination isn't confirmed immutable |

Prints the manifest key on success. With `--output json`, stdout is the full signed
run-manifest.

## restore

Fetch a bundle, re-check its checksum, `git bundle verify`, clone it out.

```sh
gitdr restore --config config.yaml \
  --repo acme/api --host github.com --date 2026-06-01 --out ./restore/api
```

| Flag | What |
|---|---|
| `--repo` | owner/name, required |
| `--host` | source host, default `github.com` |
| `--date` | backup date, `YYYY-MM-DD`, required |
| `--out` | output directory, required |

Needs only read access to the bucket. If backups were encrypted, set
`GITDR_ENCRYPTION_KEY`.

## verify

Check the manifest signature, then re-download every artifact and recompute its SHA-256.

```sh
gitdr verify --config config.yaml --manifest <manifest-object-key>
```

| Flag | What |
|---|---|
| `--manifest` | manifest object key, required |

Needs `manifest.publicKeyPath` and read access. Doesn't need the encryption key,
checksums cover the stored ciphertext. Non-zero exit on any signature or checksum
mismatch.

## doctor

Preflight. Checks tooling (`git` on PATH), validates config, checks source auth, checks
the WORM lock. Writes nothing.

```sh
gitdr doctor --config config.yaml
```

Run it before the first backup and after any credential or bucket change.

## version

```sh
gitdr version
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | success |
| 1 | run failed (config, auth, network, any repo, any artifact) |
| 2 | usage error (bad flags, missing required flag) |