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.
| Flag | Description |
|---|---|
--json | Print the result as an indented JSON document on stdout. Logs, warnings and errors stay on stderr and are not JSON. |
--no-progress | Do not show the progress bar. It is only shown when stderr is a terminal and --json is not set. |
-v, --version | Print the Stowmark version. |
-h, --help | Show 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]
| Flag | Description |
|---|---|
--repo | Repository path or URL. See repository URLs. |
--compression | none (default), gzip, zstd, lz4 or xz. |
--level | Compression level: gzip 1–9, zstd 1–22, lz4 0–9. Defaults to the algorithm default. |
--public-key | Path to the RSA public key that protects the repository key. Without it the repository is not encrypted. |
--version | Format version: 1, 2 (default) or 3. See format versions. |
--object-lock | Retain 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-mode | governance (default): users with s3:BypassGovernanceRetention, or GCS overrideUnlockedRetention, can still delete. compliance: nobody can delete until the retention ends. |
--force | Reinitialize 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.
| Flag | Description |
|---|---|
--folder | Folder 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--private-key | Current private key, to unwrap the old symmetric key. |
--public-key | Public 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--old-private-key | Private key of the current pair. |
--new-public-key | Public 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]
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--private-key | Private key of an encrypted repository, to unwrap the key that encrypts the new objects. |
--exclude | Exclude files and directories that match this pattern. Repeatable; same syntax as .stowmarkignore. Applied after every ignore file, so it can override them. |
--no-ignore-file | Do 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--private-key | Required 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.
| Flag | Description |
|---|---|
--id | Snapshot ID, for example 20260115T093000Z-1a2b3c4d. |
--repo | Repository path or URL. |
--private-key | Required 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.
| Flag | Description |
|---|---|
--id | Snapshot ID. |
--repo | Repository path or URL. |
--private-key | Private 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.
| Flag | Description |
|---|---|
--id | Snapshot ID. |
--repo | Repository path or URL. |
--destination | Directory to restore into. |
--file | Restore only this file, given by its path in the snapshot. |
--private-key | Private 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--read-data | Also download every referenced object once and verify its hash. |
--read-data-subset | Verify 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-key | Needed 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--keep-last | Keep the N most recent snapshots. |
--keep-within | Keep every snapshot newer than this duration (30d, 2w, 36h). |
--keep-daily | Keep the most recent snapshot of the last N days that have snapshots. |
--keep-weekly | Keep the most recent snapshot of the last N weeks that have snapshots. |
--keep-monthly | Keep the most recent snapshot of the last N months that have snapshots. |
--keep-yearly | Keep the most recent snapshot of the last N years that have snapshots. |
--dry-run | Only show which snapshots would be kept or forgotten, and why. |
--prune | Run prune after forgetting the snapshots. |
--private-key | Required 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--dry-run | Only report the unreferenced objects and their size; do not delete them. |
--private-key | Required 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).
| Flag | Description |
|---|---|
--repo | Repository URL (s3:// or gcs://). |
--private-key | Required 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.
| Flag | Description |
|---|---|
--repo | Repository path or URL. |
--all | Remove 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.
| Backend | Format |
|---|---|
| Local disk | /srv/backups/stowmark or any path without a scheme |
| SSH / SFTP | ssh://<user>@<host>[:<port>]/<absolute-path> (also sftp://) |
| SMB | smb://<user>@<host>[:<port>]/<share>[/<path>] |
| Amazon S3 and compatible | s3://<bucket>/<path> |
| Google Cloud Storage | gcs://<bucket>/<path> |
| WebDAV | webdav://, webdavs://, http:// or https://<host>/<path> |
Environment variables
Credentials and backend settings are read from the environment, never from flags.
| Variable | Description |
|---|---|
| SSH | |
STOWMARK_SSH_PRIVATE_KEY | Path to the SSH private key. Without it, the agent of SSH_AUTH_SOCK is used; never both. |
STOWMARK_SSH_PRIVATE_KEY_PASSPHRASE | Passphrase of that key, if it has one. |
SSH_AUTH_SOCK | Socket of the ssh-agent. |
STOWMARK_SSH_KNOWN_HOSTS | known_hosts file used to check the host key. Defaults to ~/.ssh/known_hosts. |
| SMB | |
STOWMARK_SMB_PASSWORD | Password of the SMB user. Required. |
| S3 | |
AWS_REGION | Bucket region. Credentials come from the standard AWS chain (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE…). |
STOWMARK_S3_ENDPOINT | Endpoint of an S3-compatible service (MinIO, Ceph…). |
STOWMARK_S3_PATH_STYLE | true to use path-style addressing. |
| Google Cloud Storage | |
GOOGLE_APPLICATION_CREDENTIALS | Service account credentials file. Defaults to the Application Default Credentials. |
STOWMARK_GCS_ENDPOINT | Custom endpoint, for example an emulator. |
| WebDAV | |
STOWMARK_WEBDAV_USERNAME | WebDAV user. Required. |
STOWMARK_WEBDAV_PASSWORD | WebDAV password. Required. |
| Logs and observability | |
STOWMARK_LOG_LEVEL | debug, info (default), warn or error. Logs go to stderr without an OTLP endpoint. |
OTEL_EXPORTER_OTLP_ENDPOINT | Enables OpenTelemetry traces, logs and metrics. Nothing is sent without it. |
OTEL_EXPORTER_OTLP_PROTOCOL | http/protobuf (default) or grpc. |
OTEL_SERVICE_NAME | Service 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.
| Pattern | Meaning |
|---|---|
# comment | Ignored line. |
*.log | Any file or directory named *.log, at any depth. |
node_modules/ | A trailing / matches directories only. |
/build | A pattern with a / is anchored to the directory of the ignore file. |
docs/**/*.md | ** matches any number of directories. |
!important.log | Include again. The last pattern that matches wins. |
# .stowmarkignore
node_modules/
*.log
!important.log
/build
Format versions
| Version | Description |
|---|---|
1, 2 | Objects 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. |
3 | Objects 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.