CLI reference

Every subcommand, alphabetized.

$ frostvex --help
frostvex 0.3.7 — lock-free file synchronization

USAGE:
    frostvex [OPTIONS] <COMMAND>

COMMANDS:
    init       Create a new pool
    sync       Push local changes to a remote
    pull       Pull from a peer or remote
    stat       Show pool status
    verify     Verify parity (BLAKE3 + Reed-Solomon)
    log        Show recent sync activity
    peers      Manage peer list (add, remove, list)
    prune      Remove quarantined files
    config     Print effective config
    help       Print help for a subcommand

OPTIONS:
    -c, --config <PATH>   Override config file
    -q, --quiet           Suppress non-error output
    -v, --verbose         Increase verbosity (-vv for trace)
        --json            Emit machine-readable output where applicable
    -V, --version         Print version

init

$ frostvex init <PATH> [--force]

Create a new pool from a directory. Walks the tree, hashes every file, writes .frostvex/. Idempotent unless --force is used (which will overwrite an existing pool).

sync

$ frostvex sync <PATH> --to <TARGET> [--dry-run] [--bwlimit KBPS]

One-way push. Computes the smallest delta against TARGET, ships chunks, verifies parity. TARGET can be:

host:/path — SSH-compatible syntax (note: frostvex does not use SSH; this is just a familiar form)
fvex://host/path — explicit URL form
peer://<peer-name> — a peer from your peer list

Useful flags:

flag	effect
`--dry-run`	Print the diff without transferring anything.
`--bwlimit KBPS`	Override the configured upload cap for this run.
`--no-parity`	Skip the parity verification step at the destination. Faster, less safe.
`--checkpoint SECS`	How often to flush manifest state. Default 5.

pull

$ frostvex pull <SOURCE> --to <PATH>

Reverse direction. Same target syntax as sync, just the other way around. Useful when the source machine can't reach the destination directly (hard-NAT, asymmetric firewall).

stat

$ frostvex stat [PATH]

Print pool status — file count, size, last sync, parity state, peers. --json emits machine-readable output suitable for monitoring scripts.

verify

$ frostvex verify [PATH] [--strict]

Hash every chunk, cross-check against parity. Without --strict, only the manifest's recorded hashes are checked (fast). With --strict, parity blocks are also verified — slow, but catches silent on-disk corruption.

If verification fails, the bad chunks are listed. Pair with frostvex repair (see below) to pull replacements from a peer that still has good copies.

log

$ frostvex log [PATH] [--since DURATION] [-n COUNT]

Show recent sync activity. DURATION is e.g. 2h, 3d, 1w. With --json, each line is a structured record suitable for ingestion into Loki / Vector / Splunk.

peers

$ frostvex peers list
$ frostvex peers add <HOST> --pubkey <KEY>
$ frostvex peers remove <NAME>
$ frostvex peers exchange <NAME>

peers exchange swaps pubkeys between two boxes that already have a shared secret (printed at frostvex init time). It's a slightly safer alternative to trust_on_first_use.

prune

$ frostvex prune [PATH] [--older-than DURATION]

Remove quarantined files older than the given duration (default 7d). Quarantined files live in .frostvex/quarantine/ until pruned — they don't count against the manifest.

config

$ frostvex config             # print effective config
$ frostvex config --raw       # show file contents only
$ frostvex config --check     # validate without running

Exit codes

code	meaning
`0`	Success.
`1`	Generic error (config invalid, command misused).
`2`	Network or peer unreachable.
`3`	Verification failed — corruption detected.
`4`	Conflict requires manual resolution.
`130`	Interrupted by signal (Ctrl-C). Pool remains in a recoverable state.

These are stable across the 0.3.x line. Future releases may add new codes but won't repurpose existing ones.