Docs · Sync

Local team sync.

Beta

Ledgerful sync writes signed, encrypted bundles to a directory you control. No cloud transport is involved by default.

Feature-gated build: Sync is not included in the default Ledgerful build. The source repository is a private preview, so this command requires authorized repository access. Authorized testers can install a sync-enabled binary with cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful --features sync. The standard install command elsewhere on this site does not add this optional feature.

How local sync works

Sync uses a dir:// transport — a local directory path. Each run produces a signed and encrypted bundle written to that path. Team members with access to the same directory can verify and apply bundles locally.

Local-first: The dir:// transport writes bundles to a local filesystem path. No data is sent to a cloud service. If you point the path at a network share, cloud sync folder, or SMB mount, the behavior depends entirely on the underlying filesystem.

Network share warning: Using a dir:// path over network shares — including Dropbox, Google Drive, and SMB mounts — can cause file-locking conflicts or silent data corruption when multiple machines write bundles concurrently. If you need multi-machine sync via a shared folder, ensure the transport path is on a filesystem that supports atomic writes and proper file locking for your OS combination. When in doubt, designate one machine as the writer and treat the share as read-only for all other machines.

Initialize sync

After installing a sync-enabled build, run ledgerful sync init from the repository root to set up the sync configuration and create a transport entry.

# Initialize sync with a local directory transport
ledgerful sync init

The init command creates or updates the sync configuration in config.toml and prepares the local .ledgerful/sync/ directory for bundle output.

Sync commands

All sync subcommands run from the repository root.

Command	Description
`ledgerful sync init`	Initialize the sync configuration and generate a local transport entry.
`ledgerful sync run`	Write a signed, encrypted sync bundle to the configured transport directory.
`ledgerful sync status`	Report the last sync timestamp, bundle count, and transport health.
`ledgerful sync verify`	Verify all local sync bundles against their Ed25519 signatures.
`ledgerful sync log`	Show the sync history in chronological order.

# Write a signed, encrypted bundle to the transport directory
ledgerful sync run

# Check sync health and last bundle timestamp
ledgerful sync status

# Verify all local bundles against their Ed25519 signatures
ledgerful sync verify

# Show sync history
ledgerful sync log

Sync security model

Bundles are signed and encrypted before being written to the transport directory. A receiver without the encryption key cannot read bundle contents.

Property	Mechanism
Signing	Ed25519 signature over bundle contents, using the project signing key at `~/.ledgerful/keys/private.key`.
Encryption	Bundle contents are encrypted before writing to the transport directory. Bundle contents are not readable without the encryption key.
Verification	`ledgerful sync verify` checks Ed25519 signatures on all local bundles and reports any that fail.
Transport	`dir://` only. Bundles are written to the local filesystem path you configure. No cloud transport is built in.

← Compliance export Release verification →