Skip to content
aven

Sync and backups

Sync keeps the same aven tasks available across laptops, agents, and other devices. Each client writes to its own local SQLite database first, so task capture and updates stay fast and offline-friendly.

When you run aven sync, local changes are pushed to a self-hosted server and changes from other clients are pulled back down. The server stores the shared operation log; each local database applies that log to its own task store.

Use Configuration for sync.* and daemon.* settings.

Start a server

Section titled “Start a server”
Terminal window
aven server --bind 127.0.0.1:0 --data /tmp/aven-server.sqlite

The server stores sync data in the SQLite file passed with --data and prints a listening URL:

listening url=http://127.0.0.1:<port> scope=loopback

Network requirements depend on the bind address:

Scope Use Requirements
Loopback Local testing Authentication optional
Private address LAN, VPN, or another private network sync.auth_token on the server and matching client tokens
Public address Internet-facing service --unsafe-public-bind, sync.auth_token, and TLS or a reverse proxy

Plain HTTP is intended for loopback, trusted VPNs, private networks, or external TLS termination.

Sync server URLs must use http or https, include a host, and omit username, password, query, and fragment parts.

Sync a client

Section titled “Sync a client”
Terminal window
aven sync --server http://127.0.0.1:<port>

When sync.server_url is configured, aven sync can omit --server:

Terminal window
aven sync

A local database pins the sync server it has used. Use a fresh database for a different server.

Automate sync with the daemon

Section titled “Automate sync with the daemon”

The daemon performs background sync for the configured local SQLite database.

Terminal window
aven daemon

Daemon sync requires sync.enabled = true and sync.server_url. The wake address must be loopback.

The daemon wakes after successful local mutations when possible, syncs periodically, reschedules incomplete sync quickly, and backs off after failures.

On macOS, install it as a user LaunchAgent:

Terminal window
aven daemon install
aven daemon restart
aven daemon uninstall

Package scripts can refresh an installed LaunchAgent after replacing the binary:

Terminal window
aven daemon repair --if-installed --program /path/to/aven

The repair command succeeds without changes when the LaunchAgent is absent.

Back up and move data

Section titled “Back up and move data”

You can create exact SQLite backups or export portable JSON.

Terminal window
aven backup
aven backup restore backup.sqlite --yes
Terminal window
aven export --output tasks.json
aven import tasks.json --yes
  • Backups: aven backup creates a SQLite backup.
  • Export and import: JSON exports include tasks, workspaces, projects, labels, notes, dependencies, epics, changes, field versions, conflicts, and metadata.
  • Replacement: Import and restore replace local data and require --yes. Both create a safety backup before replacement.
  • Sync metadata: Import preserves the target client id, resets the sync cursor, and skips imported pinned server metadata.

Resolve conflicts

Section titled “Resolve conflicts”

Conflicts happen when multiple clients edit the same task field between syncs. They are explicit and field based. Inspect conflicts before resolving them.

Terminal window
aven conflict list
aven conflict show APP-7KQ9 --field description
aven conflict diff APP-7KQ9 description
aven conflict export APP-7KQ9 description --dir conflicts
aven conflict resolve APP-7KQ9 description --use local

Use --value, --value-file, or --value-stdin when neither variant is the desired final value.

The TUI also has a conflicts view and conflict actions for human review.

Diagnose sync state

Section titled “Diagnose sync state”
Terminal window
aven doctor
aven doctor --integrity
aven doctor --json

For sync specifically, doctor reports the configured server, sync cursor, pending changes, conflicts, daemon wake validity, and integrity status when requested.