wdoublesync cli

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

Built on top of the wdoublesync library.

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

AI Agent Skill

wdoublesync ships with a SKILL.md that teaches AI coding agents how to use it autonomously. Once loaded, an agent can push folders to on-chain storage, pull specific versions for inspection or rollback, watch a directory for bi-directional sync, and run rebate to compact a vector's archive — all without hand-holding on the commands. This is useful when you want an agent to persist its own working state, archive project snapshots, or coordinate versioned data across sessions. The skill also covers how to combine wdoublesync with MemWal for workflows.

Installation

npm install -g @fizzyflow/wdoublesync_cli

Usage

wdoublesync push [vector-id] [path] [options]   Sync folder to a vector (creates one if no id given)
wdoublesync pull <vector-id> [path] [options]   Restore vector contents to a folder
wdoublesync info [vector-id] [path] [options]   Show chain/wallet info, or full vector metadata
wdoublesync diff <vector-id> [path] [options]   List files added/modified/deleted locally vs the on-chain version
wdoublesync watch <vector-id> [path] [options]  Watch folder: auto-push on changes, auto-pull on remote updates
wdoublesync rebate <vector-id> [path] [options] Burn archive patches and push folder as a fresh snapshot

Pass [path] explicitly — there is no need to cd into the folder first. If omitted, the current working directory is used.

Every command prints the installed CLI version as its first line of output. To update to the latest:

npm install -g @fizzyflow/wdoublesync_cli@latest

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 or compare against (pull, diff; default: latest)
--exclude <p1,p2>	Extra exclude patterns (comma-separated)
--no-compress	Disable gzip compression
--no-seal	Create a new vector public (no Seal encryption). Only applies when creating; ignored for existing vectors
--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

Pass the signing key inline:

wdoublesync push ~/my-data --key suiprivkey1...

Or export it once and drop the flag from every command:

export WDOUBLESYNC_KEY=suiprivkey1...
wdoublesync push ~/my-data

A mnemonic works instead of a raw key: --phrase "word1 word2 ...". --key and WDOUBLESYNC_KEY both take precedence over --phrase.

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

Examples

The examples below assume the key comes from WDOUBLESYNC_KEY and use the default testnet chain — add --chain mainnet to work on mainnet.

Push a folder (first time)

wdoublesync push ~/my-data

# prints the new vector id, e.g.:
#   created: 0xabc123...
#   version 1 pushed (full snapshot, gzip compressed)

By default a new vector is Seal-encrypted. To create a public (unencrypted) vector that anyone can pull without a key — and that anyone can browse in the dApp:

wdoublesync push ~/my-data --no-seal

Push an update

wdoublesync push 0xabc123... ~/my-data

# same vector on mainnet
wdoublesync push 0xabc123... ~/my-data --chain mainnet

Pull the latest version

wdoublesync pull 0xabc123... ~/restored

Pull a specific version

wdoublesync pull 0xabc123... ~/restored --version 1

Inspect a vector

# check your wallet + chain (no vector ID needed)
wdoublesync info

# full vector metadata + local sync status
wdoublesync info 0xabc123... ~/my-data

  chain:            testnet
  your wallet:      0x06bc6420b37a4898424429dcfa236f0065e12279f508337b69f6e965362fadd2

EndlessVector: 0xabc123...
  owner:            0x06bc6420b37a4898424429dcfa236f0065e12279f508337b69f6e965362fadd2
  encrypted:        yes (Seal)
  versions:         3
  binary size:      385.7 KB
  history items:    2
  archives:         0

  local tree hash:  9f2c1a4b8e...
  detecting local version...
  local matches:    version 3 of 3
  status:           up to date

See what changed locally (diff)

# list files added/modified/deleted locally compared to the latest on-chain version
wdoublesync diff 0xabc123... ~/my-data

# compare against a specific version
wdoublesync diff 0xabc123... ~/my-data --version 2

Output shows the changes from the local folder's perspective — what a push would apply:

diff: ~/my-data vs 0xabc123... (version 3 of 3)
local changes vs chain (what push would apply):
  added:      docs/new-page.md
  modified:   src/index.js
  deleted:    old-config.json

  3 change(s): 1 added, 1 modified, 1 deleted

Fast incremental pushes with a manifest

wdoublesync push 0xabc123... ~/my-data --manifest
# subsequent pushes are skipped when nothing has changed locally

Watch a folder (auto push + pull)

wdoublesync watch 0xabc123... ~/my-data
# 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... ~/my-data --debounce 3000 --poll-interval 5

Watch in push-only or pull-only mode:

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

Rebate (compact archive)

After many incremental syncs, burn old archive patches and push the current folder as a fresh single snapshot. Reduces storage cost.

wdoublesync rebate 0xabc123... ~/my-data

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... ~/my-data --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

End-to-end workflow

Create a vector, verify what was stored, then roll back to an earlier version:

export WDOUBLESYNC_KEY=suiprivkey1...

# 1. first push — creates the vector
wdoublesync push ~/my-data
#   created: 0xabc123...
#   version 1 pushed (full snapshot, gzip compressed)

# 2. verify: restore into a scratch folder and compare against the original
wdoublesync pull 0xabc123... ~/verify-tmp
diff -r ~/my-data ~/verify-tmp

# 3. change something and push again
echo "hello" > ~/my-data/new.txt
wdoublesync push 0xabc123... ~/my-data
#   version 2 pushed (diff, gzip compressed)

# 4. review the history
wdoublesync info 0xabc123... ~/my-data
#   versions:         2
#   local matches:    version 2 of 2

# 5. roll back: restore version 1 into a separate folder
wdoublesync pull 0xabc123... ~/my-data-v1 --version 1

At any point the same vector can be opened in the browser:

https://doublesync.wal.app/vector#testnet:0xabc123...

Swap testnet for mainnet to view a mainnet vector. Seal-encrypted vectors require connecting the owning wallet in the dApp.

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. diff — restores the requested version in memory (nothing is written to disk), hashes every file on both sides, and lists files added, modified, or deleted locally compared to the on-chain version.
5. 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.
6. rebate — burns all existing archive patches on-chain and pushes the current folder as a single fresh full snapshot, reducing Walrus storage costs after many incremental syncs.

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.

Links

• dApp (browse and manage vectors in the browser): https://doublesync.wal.app
• Repository: https://github.com/FizzyFlow/wdoublesync_cli
• Agent skill: SKILL.md

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