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 space apply

kutl space apply [--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 space apply

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. Runs against the space enclosing the current directory; any subdirectory of the space works, like git.

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: local (no relay token yet)
#   did:   did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
#   name:  Alice
#   email: [email protected]
#
# spaces (1 registered):
#   ✓ my-project /home/alice/code/proj relay=ws://127.0.0.1:9100/ws last-activity=12s ago signals=0
#
# relays:
#   ws://127.0.0.1:9100/ws   reachable

kutl daemon

kutl daemon <run|start|stop|status>

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

For the full picture (daemon plus spaces, relays, and identity), use kutl status.

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

kutl signal

kutl signal <create|list|view|reply|close|reopen|resolve>

Signals are flags, questions, and decisions attached to a space or its documents. Commands act on the space you are standing in; list and view cover all registered spaces when run outside one. Wherever a command takes a signal id, a unique prefix of 4+ characters works; like git commit hashes, you never type the full UUID. The table shows the flags you'll typically use; --help on any verb is exhaustive.

cd ~/code/proj/kutl
kutl signal create --kind question --message "Should the API stay v1-compatible?" --doc rfc/api.md
kutl signal list --fetch
kutl signal resolve 8c9d   # a unique id prefix is enough

kutl space feed

kutl space feed [--follow] [--format human|json]

Show this space's activity feed: document edits and signals interleaved, newest first. --follow live-tails new activity until interrupted. If the relay is unreachable, the feed degrades to locally-mirrored signals with a note.

kutl space leave

kutl space leave

Forget the space you are standing in on this machine: it is removed from this client's registry and the daemon stops syncing it. The working tree and all its files stay on disk, and your membership on the relay is untouched. Run kutl init in the folder to re-attach it any time. Refuses while the daemon is running (stop it first with kutl daemon stop).

kutl space list / kutl space status

kutl space list [--format json] · kutl space status [--format json]

space list lists every space registered on this client (name, path, relay, health). space status is the focused view of the space you are standing in: its health plus the relay it uses. Outside a space, it points you at the all-spaces kutl status instead.

kutl space participants

kutl space participants [--format json]

Lists who may act in the space you are standing in: the authorized roster, whether or not each participant is connected right now. Presence is shown as a status, not used as a filter, because you address someone precisely when they are away. Each line is the participant's name and online or offline. Names given as paths, such as an agent listed under its operator as boris/ray, show in full. The names are what kutl signal create --to accepts. --format json adds each participant's DID and the raw connection type.

kutl auth

kutl auth <login|token|logout|status>

Store token credentials for a relay. Every relay requires authentication, but self-hosted relays don't need kutl auth: with no stored token, the CLI authenticates automatically by signing a challenge with its local DID identity (the relay operator adds that DID to the relay's authorized_keys file). Use kutl auth for kutlhub and other account-backed relays. --relay defaults to the kutlhub URL wss://kutlhub.com/relay/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 auth status.

Authorizing machines: the authorized_keys file

echo 'did:key:z6Mk...' >> authorized_keys

A self-hosted relay authorizes machines through a plain text file you edit like SSH's authorized_keys: one DID per line, kept wherever $KUTL_RELAY_AUTHORIZED_KEYS_FILE points (put it under version control if you like). There is no CLI verb for this: the relay is operated through its config files. The relay live-reloads the file, so a new line takes effect on the next connection attempt without a restart.

A bare DID line grants access to every space, indefinitely. A line may also include options: scope=<space-uuid>[,<space-uuid>...] restricts it to specific spaces, expiry=<ms> sets a cutoff (Unix milliseconds), and name=<name> is what participants call that DID when they address it, and notes=<text> is an operator note that never leaves the relay. A malformed line is dropped whole: the relay fails closed and logs a dropping authorized_keys entry warning naming the reason, so a typo denies access loudly instead of widening it silently.

# Each machine prints its DID with `kutl status`.
# On the relay host, append it as a line:
echo 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK' >> authorized_keys

# Scope an agent key to one space, and name it so people can address it:
echo 'did:key:z6Mk...agent scope=8f14e45f-... name=ci-bot' >> authorized_keys

kutl config

kutl config <set|get|list>

Set or read your identity details (name, email).

kutl config set name "Alice"
kutl config set email "[email protected]"
kutl config get name
# Alice

kutl agent

kutl agent <create|list>

Provision keypairs for tool-held agents: a distinct DID per agent, held by the tool process (e.g. kutl mcp serve), SSH-style. create --name <name> mints a keypair at ~/.kutl/agents/<name>.json and prints the DID plus the authorized_keys line to grant it. list [--format json] shows the provisioned agents.

kutl mcp serve

kutl mcp serve [--poll-only] [--agent <name>]

Run the MCP server over stdio. This is the agent entry point: a Claude Code channel and MCP tool server that lets AI agents receive flags and make edits through the sync protocol. It authenticates with a tool-held agent key (named default unless --agent or $KUTL_AGENT says otherwise). Provision one with kutl agent create --name default first. When a local space is found (search directory or the client registry) it auto-subscribes; with none it still starts, and the agent discovers spaces via the list_spaces / subscribe_space tools. Pass --poll-only to poll for changes instead of subscribing to push notifications.

kutl surface

kutl surface [--dir <path>]

Copy documents from the space into its 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 document log

kutl document log <path> [--format human|json]

Show the change history of a document. Pass the file's ordinary working-tree path (e.g. notes/plan.md). Changes and any signals attached to the document interleave in reverse chronological order, similar to git log. --format json emits each change with its id (the exact input document restore --to takes), plus author, timestamp, and boundary.

kutl document log notes/plan.md

kutl document blame

kutl document blame <path> [--format human|json]

Show per-line authorship of a text document: git-blame for a CRDT. Each line is attributed to the durable author DID of its first character. Takes the working-tree path, like document log.

kutl document blame notes/plan.md

kutl document restore

kutl document restore <path> (--at <time> | --to <change-id>)

Restore a document to an earlier point in time, Google-Docs style: the historical content is reconstructed and re-asserted as a new forward edit, never a history rewrite, so a teammate's concurrent edits merge instead of being destroyed. Text documents only.

kutl document log notes/plan.md --format json   # find the change id
kutl document restore notes/plan.md --to 8c9d2e1f-...

kutl update

kutl update

Print how to update kutl for your install method (Homebrew: brew upgrade kutl). The command itself does not modify the installation.

Files and directories