Getting Started

1. Install kutl

brew install kutl/tap/kutl

The source option requires a Rust toolchain. kutl-relay is included in the same package.

2. Start a relay

The relay is the server that coordinates sync between participants. For local development, start one with authentication disabled:

KUTL_RELAY_REQUIRE_AUTH=false kutl-relay

The relay listens on ws://127.0.0.1:9100/ws by default. This is also the default relay URL that kutl init and kutl join connect to. See Self-Hosting a Relay for production deployment.

3. Initialize a space

A space is a named sync context: a directory whose contents sync with the relay. Create one inside your project:

cd /path/to/your/project
kutl init --name my-project

This creates a .kutlspace file (team config, safe to commit) and a .kutl/ directory (local state, gitignored). If you're inside a git repo, kutl creates a subfolder to keep synced documents separate from your code.

The --name flag registers a human-readable name with the relay. Other users will use this name to join. If you omit it, a name is generated automatically.

4. Start the daemon

The daemon watches your files and syncs changes with the relay in the background:

kutl daemon start

You can also run it in the foreground with kutl daemon run to see logs directly. Check status with kutl daemon status.

5. Join from another machine

On a second machine (or in a second directory), join the space by name:

kutl join my-project --relay ws://<relay-host>:9100/ws
kutl daemon start

If the relay is running on localhost, you can omit the --relay flag since it defaults to ws://127.0.0.1:9100/ws.

6. Edit and sync

Create or edit files inside the space directory. Changes sync automatically through the daemon. Any editor, script, or agent that reads and writes files becomes a sync participant. No commits, no pushes, no manual merges.

One-shot sync

If you don't want a background daemon, you can sync once and exit:

kutl sync

This pushes local changes, pulls remote changes, and exits. Useful for CI pipelines or scripts.