@txtatelier/cli

Local-first file synchronization CLI powered by Evolu.

Prerequisites

Bun runtime is required. Txtatelier uses Bun for file I/O and SQLite operations.

Install Bun:

curl -fsSL https://bun.sh/install | bash

Installation

Install globally via npm:

npm install -g @txtatelier/cli

Verify installation:

txtatelier --help

Usage

Start File Sync

Start watching and syncing files:

txtatelier

By default, this syncs ~/Documents/Txtatelier.

Custom Watch Directory

Specify a different directory:

txtatelier --watch-dir /path/to/your/files

Owner Management

Show your mnemonic (12 words - save this securely!):

txtatelier owner --show

Restore from mnemonic:

txtatelier owner --restore "word1 word2 word3 ... word12"

Reset owner (destructive - creates new identity):

txtatelier owner --reset --yes

Show configuration paths:

txtatelier owner --where

Configuration

Configuration is loaded in this priority order:

1. CLI flags (highest priority)
2. Environment variables
3. Defaults (lowest priority)

Environment Variables

All configuration can be set via environment variables:

• TXTATELIER_WATCH_DIR - Directory to watch and sync

  • Default: ~/Documents/Txtatelier

• TXTATELIER_DB_PATH - SQLite database file path

  • Default: ~/.local/share/txtatelier/txtatelier.db

• TXTATELIER_RELAY_URL - Evolu relay WebSocket URL

  • Default: wss://free.evoluhq.com

• TXTATELIER_LOGGING - Enable debug logging (0 or 1)

  • Default: 0

• TXTATELIER_MNEMONIC - Owner mnemonic for restoration (12 words)

  • Only use on first run to restore existing identity

Example

export TXTATELIER_WATCH_DIR="$HOME/Sync/Files"
export TXTATELIER_LOGGING=1
txtatelier

Running as a Systemd Service

For automatic startup and background operation, install as a systemd user service.

Installation

Run the included installation script:

# From the package directory
./scripts/install-service.sh

Or manually:

# Copy service file
cp systemd/txtatelier.service ~/.config/systemd/user/

# Copy example config
cp systemd/txtatelier.env.example ~/.config/txtatelier/txtatelier.env

# Reload systemd
systemctl --user daemon-reload

Service Management

Enable service (start on login):

systemctl --user enable txtatelier

Start service:

systemctl --user start txtatelier

Check status:

systemctl --user status txtatelier

View logs:

journalctl --user -u txtatelier -f

Stop service:

systemctl --user stop txtatelier

Disable service:

systemctl --user disable txtatelier

Configuration File

Edit ~/.config/txtatelier/txtatelier.env to configure the service:

nano ~/.config/txtatelier/txtatelier.env

After changing config, restart the service:

systemctl --user restart txtatelier

How It Works

Txtatelier maintains bidirectional sync between your filesystem and Evolu's distributed database:

1. Filesystem → Evolu: Watches for file changes and captures them into Evolu
2. Evolu → Filesystem: Listens for remote changes and materializes them to disk

Conflict Handling

When conflicts occur (file changed on disk while remote version also changed), txtatelier creates conflict files:

original-file.txt
original-file.conflict-abc123-20260314.txt

You resolve conflicts manually by choosing which version to keep.

First Run

On first run, txtatelier generates a new owner identity and displays a 12-word mnemonic:

[file-sync] Your mnemonic (save this securely!):
[file-sync]   word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12

⚠️ SAVE THIS MNEMONIC! You need it to access your data on other devices.

Multi-Device Sync

To sync files across multiple devices:

1. Install txtatelier on each device
2. Use txtatelier owner --restore "your mnemonic" on additional devices
3. All devices will automatically sync via the relay

Troubleshooting

"Another txtatelier instance is already running"

Only one instance of txtatelier can run at a time. Check for running instances:

# If running as a service
systemctl --user status txtatelier

# Check for process
ps aux | grep txtatelier

Stop the existing instance before starting a new one.

"bun is required but not installed"

Install Bun runtime:

curl -fsSL https://bun.sh/install | bash

Then restart your shell or source your profile:

source ~/.bashrc  # or ~/.zshrc

Service Won't Start

Check logs for errors:

journalctl --user -u txtatelier -n 50

Common issues:

• Bun not installed or not in PATH
• Configuration file has invalid values
• Watch directory doesn't exist or isn't writable

Sync Not Working

1. Check service is running: systemctl --user status txtatelier
2. Enable debug logging: Set TXTATELIER_LOGGING=1 in config
3. View logs: journalctl --user -u txtatelier -f
4. Check network connectivity to relay

License

MIT