API reference

Commands and every supported option

Flags can appear before or after positional arguments. Put operation-specific flags after the command. -- ends option parsing for paths beginning with -. The global options below are also included in each command's option list.

create

glesha create SET PATH... [options]

Register a backup set and its source paths locally. This creates no archive and makes no cloud requests.

Examples:

glesha create docs ~/Documents --to b2
glesha create photos ~/Pictures --to aws,b2 --compression gzip

configure

glesha configure SET [options]

Change a set's saved settings or map imported roots. Previously bound source paths cannot be replaced.

Examples:

glesha configure docs --compression gzip
glesha configure imported --root Documents=~/Documents --to b2 --catalog-to b2

run

glesha run SET [--full|--incremental] [options]

Create and upload a full backup, or an explicit incremental. Repeating a pending run resumes recorded work. Automatically named local archives are removed after all uploads and catalog publication succeed. Use --keep-archive to retain them. Explicit --output files are retained; failures keep archives for retry.

Examples:

glesha run docs
glesha run docs --incremental
glesha run docs --keep-archive
glesha run docs --incremental --assume-yes --passphrase-file /secure/archive-password --catalog-passphrase-file /secure/catalog-password --env /secure/cloud.env

retry

glesha retry SET [options]

Resume a pending backup, move, catalog publication or storage-class change. Completed uploads are reused. The original cleanup policy is preserved; --keep-archive retains the file after success. Explicitly relocated archives stay local.

Examples:

glesha retry docs
glesha retry docs --archive /new/location/backup.tar.xz.gpg

list

glesha list [--remote --from REMOTE...] [options]

Show known sets. Remote discovery registers published set descriptions without downloading backup payloads.

Examples:

glesha list
glesha list --remote --from b2 --env /secure/cloud.env

status

glesha status [SET] [options]

Show an ASCII table of catalog availability, committed snapshots, stored archive copies, remote metadata size, last upload and estimated annual storage cost in USD. status SET adds sources, snapshot identity, local database size, provider copies and separate archive/metadata estimates.

Examples:

glesha status
glesha status docs --refresh --env /secure/cloud.env

Plain status uses local records and cached measurements, without cloud requests. A local catalog is missing, local, or cached (previously synchronized or published). Cached does not promise that the remote has no newer revisions. --refresh checks recorded archive metadata and lists current metadata objects; it does not download or pull catalogs or request cold restoration.

Local SQLite bytes and compressed/encrypted remote metadata bytes are distinct. New publications record their metadata sizes; older records remain unknown until refreshed. Remote measurements count current visible objects, including discovery records, and exclude hidden or older versions. A publication after a listing may invalidate full coverage until the next refresh, rather than double-counting pending proposals.

The last upload includes recorded payload uploads and catalog publication writes. Older records without upload timestamps show - in human output. Import dates are not used as upload dates. A remote metadata measurement may provide its latest write date.

USD/year estimates include recorded archive copies across providers plus known remote metadata. They assume unchanged storage for twelve months, using the embedded pricing table, dated 2026-10-01. Unknown sizes or rates mark the estimate partial (*). Estimates exclude API requests, retrievals, egress, temporary restored copies, taxes, discounts, free tiers, pending/untracked objects and untracked object versions. They do not predict future backup growth. Intelligent-Tiering assumes Frequent Access unless archive access is observed. JSON retains its version 2 envelope and original fields; additional byte counts remain integers and USD estimates are numeric.

history

glesha history SET [options]

Show completed snapshots, newest first, including transfer and storage status.

Examples:

glesha history docs
glesha history docs --refresh --json

browse

glesha browse SET [options]

Browse a snapshot's file metadata in the local catalog. This makes no cloud requests and downloads no file content.

Examples:

glesha browse docs
glesha browse docs --path Documents --recursive
glesha browse docs --snapshot SNAPSHOT_ID --recursive --json

restore

glesha restore SET --into DIR [options]

Reconstruct a full snapshot in a new destination. Cold retrieval requires separate, explicit consent.

Examples:

glesha restore docs --into ~/recovered
glesha restore docs --snapshot SNAPSHOT_ID --into ~/recovered --from b2,aws
glesha restore docs --into ~/recovered --request-retrieval --retrieval bulk

import

glesha import SET (--file FILE | --from REMOTE --key KEY) [options]

Catalog an existing full archive without changing its encrypted bytes or uploading a replacement payload.

Examples:

glesha import old-docs --file encb-old.tar.gz.gpg
glesha import old-docs --from b2 --key backups/encb-old.tar.gz.gpg
glesha import old-docs --file encb-old.tar.gz.gpg --from b2 --key backups/encb-old.tar.gz.gpg --deep-verify

move

glesha move SET --to REMOTE [options]

Copy and verify the complete set history before switching providers. Existing source copies are retained.

Examples:

glesha move docs --to b2
glesha move docs --to other-remote --request-retrieval --retrieval bulk

archive

glesha archive PATH... [options]

Create a standalone encrypted tar archive. No set name or cloud provider is needed.

Examples:

glesha archive ~/Documents
glesha archive ~/Documents ~/Pictures --compression gzip --output personal.tar.gz.gpg
glesha archive ~/Documents --archive-mode stream --memory-max 128MiB --passphrase-file /secure/archive-password

decrypt

glesha decrypt FILE [options]

Validate an encrypted archive and write its compressed tar to a new output file.

Examples:

glesha decrypt personal.tar.xz.gpg
glesha decrypt encb-old.tar.gz.gpg --output recovered.tar.gz --passphrase-file /secure/archive-password

extract

glesha extract FILE --into DIR [options]

Validate and extract an encrypted or plaintext compressed tar into a new directory.

Examples:

glesha extract personal.tar.xz.gpg --into ~/recovered
glesha extract recovered.tar.gz --into ~/recovered

upload

glesha upload FILE --to REMOTE... [options]

Upload an existing file. Replacing an existing object key requires --force.

Examples:

glesha upload personal.tar.xz.gpg --to b2
glesha upload personal.tar.xz.gpg --to aws,b2 --key backups/personal.tar.xz.gpg

download

glesha download KEY --from REMOTE... [options]

Download encrypted bytes from explicitly selected providers, trying them in the supplied order.

Examples:

glesha download backups/personal.tar.xz.gpg --from b2,aws
glesha download backups/personal.tar.xz.gpg --from b2 --output personal.tar.xz.gpg

catalog

glesha catalog pull|push|reconcile|abandon SET [options]

Synchronize metadata explicitly. Pull preserves the old local catalog; reconcile preserves conflicting histories; abandon preserves pending data.

Examples:

glesha catalog pull docs
glesha catalog push old-docs
glesha catalog reconcile docs
glesha catalog abandon docs

storage-class

glesha storage-class SET --snapshot ID --class CLASS [options]

Change an AWS object's storage class with server-side copy. Archive identity and older versions are retained.

Examples:

glesha storage-class docs --snapshot SNAPSHOT_ID --class DEEP_ARCHIVE

check

glesha check --to REMOTE... [options]

Test every selected provider using a small owned temporary object. Print separate safety, write, metadata, verified read and cleanup results, followed by a summary. OK means verified, FAILED includes the error, and SKIPPED makes no access claim. A failed provider does not stop the remaining checks.

Buckets with default Object Lock retention are not uploaded to during checks. If cleanup fails, the remaining key/version is printed; existing objects are never replaced or deleted. status continues to describe backups rather than creating test objects.

Examples:

glesha check --to b2 --env /secure/cloud.env
glesha check --to aws,b2 --env /secure/cloud.env
glesha check --to b2 --json --env /secure/cloud.env

help

glesha help
glesha help run
glesha help catalog pull

Shows help without reading configuration or credentials. Accepts the global options; --help/-h show help and --version shows the executable version.

version

glesha version
glesha -v
glesha -version
glesha --version

All forms print glesha VERSION (GIT_SHA) and exit successfully. Development builds print glesha dev (unknown) unless version/revision values are embedded at build time. Configuration and credential files are not loaded. The version subcommand accepts the global options; glesha version --help or glesha help version lists them. Extra positional arguments are rejected. See man/glesha-version.1.

Exit status

Bounded disk space

glesha run docs --chunked --spool-max 128M creates independently encrypted chunks instead of one archive. 128M and 1.1G use decimal units; 128MiB uses binary units. The default spool limit is 128MiB. create and configure can save these settings; run --chunked=false selects a single archive.

Chunked runs reject --output and --keep-archive. Completed chunks are uploaded and removed locally before continuing. Retrying re-reads the source and checks completed chunks, then uploads remaining work; changed sources cause an error. Repeat run SET with the original archive passphrase to resume unfinished chunks. retry SET can finish publication once all payload chunks and the descriptor are ready. A chunk contains a fragment of the tar stream. For manual recovery, decrypt the manifest, decrypt and decompress its chunks in order, then concatenate the uncompressed fragments before extracting the tar stream.

The encrypted manifest.json.gpg records chunk order, sizes and checksums. Keep it with the chunks for recovery. Single-file and chunked snapshots can share a history. move, storage-class, raw archive and raw archive import currently accept single-file snapshots only. Failed runs can leave uncommitted remote chunks; glesha does not delete these automatically.