# Command reference

`snapdir` creates content-addressable directory snapshots. Every subcommand
shares a common set of global options and reads the same `SNAPDIR_*` environment
variables. This page documents that shared surface; each subcommand has its own
page linked below.

```text
snapdir [OPTIONS] <COMMAND>
```

## Commands

| Command | Description |
| --- | --- |
| [`manifest`](snapdir-manifest.md) | Print the manifest of a directory |
| [`id`](snapdir-id.md) | Print the manifest ID of a directory or a manifest piped via stdin |
| [`stage`](snapdir-stage.md) | Save a snapshot of a directory into the local cache |
| [`push`](snapdir-push.md) | Push a snapshot to a store given its path or a staged manifest ID |
| [`fetch`](snapdir-fetch.md) | Fetch a snapshot from a store into the local cache |
| [`pull`](snapdir-pull.md) | Fetch a snapshot from a store and check it out to the given path |
| [`checkout`](snapdir-checkout.md) | Check out a snapshot to a directory |
| [`verify`](snapdir-verify.md) | Verify the integrity of a staged snapshot |
| [`verify-cache`](snapdir-verify-cache.md) | Verify the integrity of the local cache |
| [`flush-cache`](snapdir-flush-cache.md) | Flush the local cache |
| [`locations`](snapdir-locations.md) | List directories and stores where snapshots have been recorded |
| [`ancestors`](snapdir-ancestors.md) | List ancestor snapshot IDs and their locations |
| [`revisions`](snapdir-revisions.md) | List snapshot IDs created on a location (store or absolute path) |
| [`defaults`](snapdir-defaults.md) | Print default settings and arguments |
| [`sync`](snapdir-sync.md) | Copy a snapshot directly between two stores |
| [`version`](snapdir-version.md) | Print the version |

## Global options

These options are accepted by every subcommand.

| Option | Description |
| --- | --- |
| `--cache-dir <DIR>` | Directory where the object cache is stored. Env: `SNAPDIR_CACHE_DIR`. |
| `--catalog <NAME>` | Catalog adapter to use. Env: `SNAPDIR_CATALOG`. |
| `--store <URI>` | Store URI: `protocol://location/path`. Env: `SNAPDIR_STORE`. |
| `--checksum <ALGO>` | Checksum algorithm for snapshots: `blake3` (default), `md5`, or `sha256`. Env: `SNAPDIR_CHECKSUM`. |
| `--id <ID>` | Snapshot ID to operate on. |
| `--exclude <PATTERN>` | Exclude paths matching `PATTERN`. |
| `--paths <PATTERN>` | Only include paths matching `PATTERN`. |
| `--linked` | Use symlinks instead of copies. |
| `--force` | Force an action to run. |
| `--purge` | Purge objects with invalid checksums. |
| `--keep` | Keep the staging directory. |
| `--dryrun` | Run without making any changes. |
| `--verbose` | Enable verbose output. |
| `--debug` | Enable debug output. |
| `--no-progress` | Disable the live progress line (transfers still run). Env: `SNAPDIR_NO_PROGRESS`. |
| `-q`, `--quiet` | Suppress stderr banners and the live progress line. |
| `--color <WHEN>` | When to colorize progress output: `auto` (default), `always`, or `never`. |
| `--location <DIR\|STORE>` | Context (directory or store) for catalog queries. |
| `-j`, `--jobs <N>` | Max concurrent object transfers (`0`/auto = number of CPUs, capped). Env: `SNAPDIR_JOBS`. |
| `--limit-rate <RATE>` | Limit total transfer bandwidth, e.g. `10M`, `512K`, `1G` (wget-style; aggregate across all transfers). Env: `SNAPDIR_LIMIT_RATE`. |
| `--adaptive[=<FRACTION>]` | Adaptively tune transfer concurrency/bandwidth toward a fraction (default `0.8`) of measured CPU/network capacity; backs off under contention. Opt-in; default is full speed. Env: `SNAPDIR_ADAPTIVE`. |
| `--max-jobs <N>` | Adaptive concurrency ceiling (only meaningful with `--adaptive`). Env: `SNAPDIR_MAX_JOBS`. |
| `--max-retries <N>` | Total attempts per network request, including the first (default `5`). Env: `SNAPDIR_MAX_RETRIES`. |
| `--retry-base-ms <MS>` | Base backoff delay (ms) for request retries (default `250`). Env: `SNAPDIR_RETRY_BASE_MS`. |
| `--retry-max-ms <MS>` | Maximum backoff delay (ms) for request retries (default `30000`). Env: `SNAPDIR_RETRY_MAX_MS`. |
| `--max-requests <N>` | Cap request rate (req/s); `0`/unset uses the per-backend default. Env: `SNAPDIR_MAX_REQUESTS`. |
| `-h`, `--help` | Print help (see a summary with `-h`). |
| `-V`, `--version` | Print version. |

## Environment variables

Each global option above that is backed by an environment variable lists it
inline. The full set of `SNAPDIR_*` variables honored by the CLI:

| Variable | Equivalent option |
| --- | --- |
| `SNAPDIR_CACHE_DIR` | `--cache-dir` |
| `SNAPDIR_CATALOG` | `--catalog` |
| `SNAPDIR_STORE` | `--store` |
| `SNAPDIR_CHECKSUM` | `--checksum` |
| `SNAPDIR_NO_PROGRESS` | `--no-progress` |
| `SNAPDIR_JOBS` | `-j`, `--jobs` |
| `SNAPDIR_LIMIT_RATE` | `--limit-rate` |
| `SNAPDIR_ADAPTIVE` | `--adaptive` |
| `SNAPDIR_MAX_JOBS` | `--max-jobs` |
| `SNAPDIR_MAX_RETRIES` | `--max-retries` |
| `SNAPDIR_RETRY_BASE_MS` | `--retry-base-ms` |
| `SNAPDIR_RETRY_MAX_MS` | `--retry-max-ms` |
| `SNAPDIR_MAX_REQUESTS` | `--max-requests` |

Run [`snapdir defaults`](snapdir-defaults.md) to print the effective settings,
including every `SNAPDIR_*` variable currently in your environment.

## Retries & backoff

On transient failures — HTTP `429`/`503`, S3 `SlowDown`, GCS `RESOURCE_EXHAUSTED`,
and network timeouts — snapdir retries the request with **full-jitter exponential
backoff** (`--max-retries` / `--retry-base-ms` / `--retry-max-ms`). When the server
sends a `Retry-After` header, snapdir honors it as a floor: it never retries sooner
than the server asked, but may wait longer if the jittered backoff is larger.
Non-transient errors — `404`, `403`, missing objects, or bad credentials — fail fast
without retrying. The storage SDKs' own retry logic is disabled, so this is the single
retry policy for every backend. The per-backend request and bandwidth caps,
`--max-requests`, and `--limit-rate` are covered in the
[Stores guide](../guide/stores.md).

## Stores

The `--store` URI selects a backend by scheme. Built-in schemes are dispatched to
matching `snapdir-<scheme>-store` shims:

| Scheme | Backend |
| --- | --- |
| `file://` | Local filesystem |
| `s3://` | Amazon S3 (and S3-compatible) |
| `gs://` | Google Cloud Storage |
| `b2://` | Backblaze B2 |

See [Stores and cache](../concepts/stores-and-cache.md) and the
[Stores guide](../guide/stores.md) for details.

## See also

- [Quickstart](../quickstart.md)
- [Snapshotting guide](../guide/snapshotting.md)
- [Pushing and pulling guide](../guide/pushing-pulling.md)
- [Content addressing](../concepts/content-addressing.md)
- [Manifests](../concepts/manifests.md)