CLI Reference

kutl init

kutl init [--relay <url>] [--name <name>] [--dir <path>] [--subfolder <name>]

Initialize a new kutl space in a directory. Creates .kutlspace and .kutl/, generates a DID identity if one doesn't exist, and registers the space name with the relay.

kutl init --name my-project

kutl update

kutl update [--dir <path>]

Refresh the kutl-managed section of AGENTS.md against the running binary's instructions template. Use this when AGENTS.md was generated by an older kutl version and is out of date. Anchors at the space's project root (the git repo root if any, otherwise the space directory) and bails if no kutl space is present at or under the anchor.

kutl update

kutl join

kutl join [<target>] [--relay <url>] [--dir <path>] [--subfolder <name>]

Join an existing space. The target can be:

• A bare name (e.g. my-project) — resolved via the default or specified relay
• An owner/slug (e.g. alice/my-project), which connects via kutlhub
• A full invite URL (e.g. https://...), with the relay extracted from the URL

If invoked inside a directory with an existing .kutlspace, the space name from that file is used and the target argument may be omitted.

# Join by name (uses default relay)
kutl join my-project

# Join by name with an explicit relay
kutl join my-project --relay ws://relay.example.com:9100/ws

kutl sync

kutl sync [--dir <path>]

Push local changes and pull remote changes, then exit. A one-shot alternative to running the daemon continuously. Useful for CI pipelines or scripts.

kutl status

kutl status [--format human|json]

Show client diagnostic state: daemon and desktop tray liveness, registered spaces, identity, and relay reachability. Works whether the daemon is running or not. Run from any directory.

kutl status
# daemon: running (PID 12345, $KUTL_HOME=~/.kutl)
# identity: Alice ([email protected])
#
# spaces (1 registered):
#   ✓ my-project    /home/alice/code/proj    relay=ws://127.0.0.1:9100/ws last-activity=12s ago
#
# relays:
#   ws://127.0.0.1:9100/ws   reachable

kutl daemon

kutl daemon <run|start|stop>

Manage the background daemon that watches files and syncs with the relay.

To inspect daemon liveness and registered spaces, use kutl status.

kutl daemon start
kutl status
# daemon: running (PID 12345, $KUTL_HOME=~/.kutl)

kutl auth

kutl auth <login|token|logout>

Authenticate with a relay. Not required for OSS relays running on loopback (the default), where auth is automatically disabled. Required for kutlhub and any relay bound off-loopback (where KUTL_RELAY_REQUIRE_AUTH defaults to true). --relay defaults to the kutlhub URL wss://relay.kutlhub.com/ws; pass an explicit URL to authenticate against a self-hosted relay.

Credentials are stored in ~/.kutl/auth.json. The KUTL_TOKEN environment variable takes precedence over stored credentials. To see which identity is currently active, use kutl status.

kutl config

kutl config set <key> <value>

Set your local identity (DID) configuration. To read the current identity and other client state, use kutl status.

kutl config set name "Alice"
kutl config set email "[email protected]"
kutl status

kutl watch

kutl watch

Watch a space for signals. Runs as a Claude Code channel and MCP tool server over stdio. Must be invoked inside a space directory. This enables AI agents to participate in kutl spaces by receiving flags and making edits through the sync protocol.

kutl surface

kutl surface [--dir <path>]

Copy documents from the space into a parent directory (or a configured surface target). Intended for git coexistence: kutl is the source of truth for documents, and surface lifts them into your git working tree. Always overwrites the target.

Requires a [surface] section in .kutlspace with a target path configured.

kutl log

kutl log <path>

Show the change history of a .dt document file. Displays changes in reverse chronological order, similar to git log.

kutl log .kutl/docs/notes.dt

Files and directories