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.

snapdir [OPTIONS] <COMMAND>

Commands

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

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