wdoublesync cli

CLI tool to sync local folders to Walrus decentralised storage on the Sui network.

Built on top of the wdoublesync library.

Each push stores a versioned, gzip-compressed snapshot (or diff) inside an EndlessVector on-chain object. Any past version can be restored at any time with pull. Folders can optionally be encrypted with Seal.

Installation

pnpm install
# make the binary globally available (optional)
pnpm link --global

Usage

wdoublesync push [vector-id] [options]   Sync current folder to a vector (creates one if no id given)
wdoublesync pull <vector-id> [options]   Restore vector contents to the current folder
wdoublesync info <vector-id> [options]   Show vector metadata and local sync status
wdoublesync watch <vector-id> [options]  Watch folder and auto-push on changes, auto-pull on remote updates

Options

Flag	Description
--chain <name>	Chain: mainnet, testnet, devnet, localnet (default: testnet)
--key <suiprivkey>	Sui private key (or set WDOUBLESYNC_KEY env var)
--phrase <mnemonic>	Mnemonic phrase instead of a raw key
--version <n>	Version to restore (pull only, default: latest)
--exclude <p1,p2>	Extra exclude patterns (comma-separated)
--no-compress	Disable gzip compression
--manifest	Write/use .wdoublesync manifest for faster change detection
--force-snapshot	Push a full snapshot regardless of prior history (repairs a corrupt vector)
--poll-interval <s>	watch: seconds between remote version checks (default: 2)
--debounce <ms>	watch: quiet period in ms before pushing after a local change (default: 1000)
--push-only	watch: disable auto-pull
--pull-only	watch: disable auto-push
--help	Show help

Authentication

Supply a signing key in one of three ways (checked in order):

1. --key suiprivkey1...
2. --phrase "word1 word2 ..."
3. WDOUBLESYNC_KEY environment variable

pull and info work without a key for public (unencrypted) vectors. A key is required for Seal-encrypted vectors and for any push.

Examples

Push current folder (first time)

cd my-project
wdoublesync push --chain testnet --key suiprivkey1...
# prints the new vector id, e.g.:
#   created: 0xabc123...
#   version 1 pushed (full snapshot, gzip compressed)

Push an update

wdoublesync push 0xabc123... --chain testnet --key suiprivkey1...
# version 2 pushed (diff, gzip compressed)

Pull the latest version into the current folder

mkdir restored && cd restored
wdoublesync pull 0xabc123... --chain testnet

Pull a specific version

wdoublesync pull 0xabc123... --chain testnet --version 1

Inspect a vector without touching the local folder

wdoublesync info 0xabc123... --chain testnet

Fast incremental pushes with a manifest

wdoublesync push 0xabc123... --chain testnet --key suiprivkey1... --manifest
# subsequent pushes are skipped when nothing has changed locally

Watch a folder (auto push + pull)

wdoublesync watch 0xabc123... --chain testnet --key suiprivkey1...
# pushes local changes 1 s after the last edit
# pulls remote updates every 2 s
# Ctrl-C to stop

Tune the timing:

wdoublesync watch 0xabc123... --debounce 3000 --poll-interval 5

Watch in push-only or pull-only mode:

wdoublesync watch 0xabc123... --push-only   # no auto-pull
wdoublesync watch 0xabc123... --pull-only   # no auto-push (read-only mirror)

Repair a corrupt vector with a force snapshot

If a diff patch was pushed against a stale base (e.g. a race condition in watch), subsequent pulls will fail. Fix it by pushing a new full snapshot:

wdoublesync push 0xabc123... --chain testnet --key suiprivkey1... --force-snapshot
# skips chain replay and pushes the current folder as a self-contained full snapshot
# restore() will recover from this snapshot, skipping any corrupt diffs before it

How it works

1. push — scans the current directory, computes a tree hash, and compares it against the last stored version. If changes are detected, a compressed diff (or full snapshot on the first push) is uploaded to Walrus and appended to the EndlessVector on-chain.
2. pull — reads the requested version from the EndlessVector, decrypts it if Seal-encrypted, and writes only changed files to disk. Files absent from the stored version are deleted.
3. info — reads EndlessVector metadata from the chain (version count, binary size, history) and checks whether the local folder matches any stored version.
4. watch — combines push and pull in a loop. A filesystem watcher triggers a debounced push on local changes. A poll interval checks the remote vector for new versions and pulls them if found. Push and pull never run concurrently.

Default excludes

The following are always excluded from snapshots: node_modules, .git, .env, .DS_Store, .wdoublesync, pnpm-lock.yaml, package-lock.json. Add more with --exclude.

Dependencies

Package	Role
@fizzyflow/wdoublesync	Folder-diff / snapshot layer
@fizzyflow/doublesync	Core CDC store and snapshot primitives
@fizzyflow/endless-vector	On-chain EndlessVector (Sui + Walrus + Seal)
suidouble	Sui client / key management