DOCUMENTATION

Command reference

Every Stowmark command and option. Run stowmark <command> --help to see the same information from the binary you have installed.

Getting started

A repository stores the configuration, one manifest per snapshot and the content-addressed objects. Encryption is optional: create an RSA key pair, initialize the repository with the public key and pass the private key to the commands that read or write data.

stowmark key generate --folder ~/.stowmark/keys
stowmark init --repo ~/backups/documents --version 3 --compression zstd \
  --public-key ~/.stowmark/keys/stowmark-public.pem
stowmark snapshot create ./documents --repo ~/backups/documents \
  --private-key ~/.stowmark/keys/stowmark-private.pem
stowmark snapshot list --repo ~/backups/documents \
  --private-key ~/.stowmark/keys/stowmark-private.pem

Every command that reads or writes repository data takes a repository lock. Create, restore, verify and check share it; init, rekey, rewrap, forget and prune need it exclusively.

Global flags

These flags are accepted by every command.

FlagDescription
--jsonPrint the result as an indented JSON document on stdout. Logs, warnings and errors stay on stderr and are not JSON.
--no-progressDo not show the progress bar. It is only shown when stderr is a terminal and --json is not set.
-v, --versionPrint the Stowmark version.
-h, --helpShow the help of any command.

stowmark init

Initialize a new repository. The compression, the format version and the encryption are fixed at this point.

stowmark init --repo <url> [flags]
FlagDescription
--repoRepository path or URL. See repository URLs.
--compressionnone (default), gzip, zstd, lz4 or xz.
--levelCompression level: gzip 1–9, zstd 1–22, lz4 0–9. Defaults to the algorithm default.
--public-keyPath to the RSA public key that protects the repository key. Without it the repository is not encrypted.
--versionFormat version: 1, 2 (default) or 3. See format versions.
--object-lockRetain every object, manifest and the config for this period (for example 30d, 2w or 36h) with S3 Object Lock or GCS object retention. The bucket must have it enabled, versioning and no default retention.
--object-lock-modegovernance (default): users with s3:BypassGovernanceRetention, or GCS overrideUnlockedRetention, can still delete. compliance: nobody can delete until the retention ends.
--forceReinitialize an existing repository.
stowmark init --repo s3://backups/documents --version 3 --compression zstd --level 6 \
  --public-key keys/stowmark-public.pem --object-lock 30d --object-lock-mode compliance

stowmark key

Manage the encryption keys. Objects are encrypted with a random symmetric key (AES-256-GCM), which is stored in the config wrapped with your RSA public key (RSA-OAEP-SHA256).

key generate

Create a new RSA key pair: stowmark-public.pem and stowmark-private.pem.

FlagDescription
--folderFolder where the key pair is written.
stowmark key generate --folder keys

key rekey

Rotate the symmetric key and re-encrypt every object with it, in a new key generation. Use it when the symmetric key must be revoked. The old generation is removed at the end; if the command is interrupted, prune removes what is left.

FlagDescription
--repoRepository path or URL.
--private-keyCurrent private key, to unwrap the old symmetric key.
--public-keyPublic key that protects the new symmetric key.
stowmark key rekey --repo /srv/backups/stowmark \
  --private-key keys/stowmark-private.pem --public-key keys/stowmark-public.pem

key rewrap

Replace the RSA key pair. The symmetric key and the objects do not change: only the wrapped key in the config. Afterwards every command needs the new private key.

FlagDescription
--repoRepository path or URL.
--old-private-keyPrivate key of the current pair.
--new-public-keyPublic key of the new pair.
stowmark key rewrap --repo /srv/backups/stowmark \
  --old-private-key keys/stowmark-old-private.pem --new-public-key keys/stowmark-new-public.pem

stowmark snapshot

Create, inspect, verify and restore snapshots.

snapshot create

Back up a directory. Unchanged files are not stored again, and files of 8 MiB or more are split into 4 MiB chunks. Files and directories that match a .stowmarkignore file or an --exclude pattern are skipped (see exclude patterns). Symlinks and special files that formats 1 and 2 cannot store are reported as a warning on stderr.

stowmark snapshot create <source> --repo <url> [flags]
FlagDescription
--repoRepository path or URL.
--private-keyPrivate key of an encrypted repository, to unwrap the key that encrypts the new objects.
--excludeExclude files and directories that match this pattern. Repeatable; same syntax as .stowmarkignore. Applied after every ignore file, so it can override them.
--no-ignore-fileDo not read .stowmarkignore files; only --exclude patterns apply.
stowmark snapshot create ~/projects --repo /srv/backups/stowmark \
  --exclude 'node_modules/' --exclude '*.log' --private-key keys/stowmark-private.pem

snapshot list

List the snapshots of the repository.

FlagDescription
--repoRepository path or URL.
--private-keyRequired for an encrypted format 3 repository, whose manifests are encrypted.

snapshot get

Show the manifest of a snapshot: its source and every file with its hash, size and chunks.

FlagDescription
--idSnapshot ID, for example 20260115T093000Z-1a2b3c4d.
--repoRepository path or URL.
--private-keyRequired for an encrypted format 3 repository.

snapshot verify

Read every object of a snapshot and check its hash. On encrypted repositories this also authenticates the data.

FlagDescription
--idSnapshot ID.
--repoRepository path or URL.
--private-keyPrivate key of an encrypted repository.

snapshot restore

Restore a whole snapshot or a single file. Without --destination, files are restored to their original paths inside the source directory of the snapshot. Each file is written to a temporary file, verified and then renamed. Format 3 also restores directories, symlinks, permissions and modification times.

FlagDescription
--idSnapshot ID.
--repoRepository path or URL.
--destinationDirectory to restore into.
--fileRestore only this file, given by its path in the snapshot.
--private-keyPrivate key of an encrypted repository.
stowmark snapshot restore --id <snapshot-id> --repo /srv/backups/stowmark \
  --file reports/2026.pdf --destination /tmp/restore

stowmark check

Check the whole repository: every manifest can be read and every object it references exists. It exits with an error if a manifest is corrupt or an object is missing or corrupt. Orphan objects, stale locks, old key generations and items whose retention has ended are reported as warnings.

FlagDescription
--repoRepository path or URL.
--read-dataAlso download every referenced object once and verify its hash.
--read-data-subsetVerify only part of the objects: a random percentage (10%) or a stable part (2/7). Running parts 1/7 to 7/7 covers everything.
--private-keyNeeded to read the data, or the format 3 manifests, of an encrypted repository.
stowmark check --repo /srv/backups/stowmark --read-data-subset 10% \
  --private-key keys/stowmark-private.pem

stowmark forget

Apply a retention policy to the snapshots of each source and delete the manifests it does not keep. Periods are counted in UTC; a snapshot kept by any rule is kept. Forgetting does not free space: run prune afterwards or add --prune.

FlagDescription
--repoRepository path or URL.
--keep-lastKeep the N most recent snapshots.
--keep-withinKeep every snapshot newer than this duration (30d, 2w, 36h).
--keep-dailyKeep the most recent snapshot of the last N days that have snapshots.
--keep-weeklyKeep the most recent snapshot of the last N weeks that have snapshots.
--keep-monthlyKeep the most recent snapshot of the last N months that have snapshots.
--keep-yearlyKeep the most recent snapshot of the last N years that have snapshots.
--dry-runOnly show which snapshots would be kept or forgotten, and why.
--pruneRun prune after forgetting the snapshots.
--private-keyRequired for an encrypted format 3 repository.
stowmark forget --repo /srv/backups/stowmark \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

Snapshots still under Object Lock retention cannot be deleted yet; they are reported as postponed and a later run removes them.

stowmark prune

Remove the objects that no manifest references, the objects of old key generations left by an interrupted rekey and the temporary files left by interrupted writes. It takes an exclusive lock, so no other command can use the repository while it runs.

FlagDescription
--repoRepository path or URL.
--dry-runOnly report the unreferenced objects and their size; do not delete them.
--private-keyRequired for an encrypted format 3 repository.

stowmark retention extend

Extend the S3 Object Lock or GCS object retention of the config, every manifest and every object they reference to one full period from now, for the items whose retention ends within half a period. Objects written once and reused by later snapshots keep their first retention, so run it regularly (for example from cron, more often than half the period).

FlagDescription
--repoRepository URL (s3:// or gcs://).
--private-keyRequired for an encrypted format 3 repository.

stowmark unlock

Remove the repository locks that have not been refreshed for 30 minutes, for example after a crash. Running commands refresh their lock every 5 minutes.

FlagDescription
--repoRepository path or URL.
--allRemove every lock, including locks held by running commands.

stowmark completion

Generate the autocompletion script for bash, zsh, fish or powershell.

stowmark completion zsh > "${fpath[1]}/_stowmark"

Repository URLs

The --repo value selects the backend. The source and restored files always stay on the local machine.

BackendFormat
Local disk/srv/backups/stowmark or any path without a scheme
SSH / SFTPssh://<user>@<host>[:<port>]/<absolute-path> (also sftp://)
SMBsmb://<user>@<host>[:<port>]/<share>[/<path>]
Amazon S3 and compatibles3://<bucket>/<path>
Google Cloud Storagegcs://<bucket>/<path>
WebDAVwebdav://, webdavs://, http:// or https://<host>/<path>

Environment variables

Credentials and backend settings are read from the environment, never from flags.

VariableDescription
SSH
STOWMARK_SSH_PRIVATE_KEYPath to the SSH private key. Without it, the agent of SSH_AUTH_SOCK is used; never both.
STOWMARK_SSH_PRIVATE_KEY_PASSPHRASEPassphrase of that key, if it has one.
SSH_AUTH_SOCKSocket of the ssh-agent.
STOWMARK_SSH_KNOWN_HOSTSknown_hosts file used to check the host key. Defaults to ~/.ssh/known_hosts.
SMB
STOWMARK_SMB_PASSWORDPassword of the SMB user. Required.
S3
AWS_REGIONBucket region. Credentials come from the standard AWS chain (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE…).
STOWMARK_S3_ENDPOINTEndpoint of an S3-compatible service (MinIO, Ceph…).
STOWMARK_S3_PATH_STYLEtrue to use path-style addressing.
Google Cloud Storage
GOOGLE_APPLICATION_CREDENTIALSService account credentials file. Defaults to the Application Default Credentials.
STOWMARK_GCS_ENDPOINTCustom endpoint, for example an emulator.
WebDAV
STOWMARK_WEBDAV_USERNAMEWebDAV user. Required.
STOWMARK_WEBDAV_PASSWORDWebDAV password. Required.
Logs and observability
STOWMARK_LOG_LEVELdebug, info (default), warn or error. Logs go to stderr without an OTLP endpoint.
OTEL_EXPORTER_OTLP_ENDPOINTEnables OpenTelemetry traces, logs and metrics. Nothing is sent without it.
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf (default) or grpc.
OTEL_SERVICE_NAMEService name. Defaults to stowmark.

Exclude patterns

A .stowmarkignore file uses a subset of the .gitignore syntax. It applies to its own directory and below, and can override the files of its parent directories. --exclude patterns are applied last.

PatternMeaning
# commentIgnored line.
*.logAny file or directory named *.log, at any depth.
node_modules/A trailing / matches directories only.
/buildA pattern with a / is anchored to the directory of the ignore file.
docs/**/*.md** matches any number of directories.
!important.logInclude again. The last pattern that matches wins.
# .stowmarkignore
node_modules/
*.log
!important.log
/build

Format versions

VersionDescription
1, 2Objects are identified by the SHA-256 of their compressed data. Only regular files are stored. Version 2 is the default, for compatibility with existing repositories.
3Objects are identified by their content (HMAC-SHA256 when encrypted), so changing the compression keeps deduplication. Encryption is streamed, manifests are encrypted, and directories, symlinks, permissions and modification times are stored.

There is no migration command: create a new repository with --version 3 to use it.