CLI Reference

Every kutl command, its flags, and usage examples.

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.

Flag	Type	Default	Description
`--relay`	URL	ws://127.0.0.1:9100/ws	Relay WebSocket URL
`--name`	string	auto-generated	Human-readable space name
`--dir`	path	current directory	Target directory
`--subfolder`	string	"kutl" (prompted)	Subfolder name inside a git repo

Example

kutl init --name my-project

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.

Flag	Type	Default	Description
`--relay`	URL	—	Relay WebSocket URL (inferred from target when possible)
`--dir`	path	current directory	Target directory
`--subfolder`	string	—	Subfolder name inside a git repo

Examples

# 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.

Flag	Type	Default	Description
`--dir`	path	current directory	Target directory

kutl daemon

kutl daemon <run|start|stop|status>

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

Subcommand	Description
`run`	Run in the foreground (watches all registered spaces)
`start`	Start as a background process (PID written to `~/.kutl/daemon.pid`)
`stop`	Stop the running daemon (graceful SIGTERM, then SIGKILL)
`status`	Show daemon status and list registered spaces

Example

kutl daemon start
kutl daemon status
# daemon is running (PID 12345)
#   /path/to/project: my-project (ws://127.0.0.1:9100/ws)

kutl auth

kutl auth <login|token|status|logout>

Authenticate with a relay. Not required for OSS relays with authentication disabled. Required for kutlhub and relays with KUTL_RELAY_REQUIRE_AUTH=true.

Subcommand	Description
`login [--token <TOKEN>] [--relay <URL>]`	Authenticate via OAuth device flow (opens browser), or store a token directly with `--token`
`token <TOKEN> [--relay <URL>]`	Store a personal access token for a relay
`status`	Show current authentication status (token prefix, account, relay)
`logout`	Delete stored credentials

Credentials are stored in ~/.kutl/credentials. The KUTL_TOKEN environment variable takes precedence over stored credentials.

kutl config

kutl config <set|show>

View or update your local identity (DID) configuration.

Subcommand	Description
`set <key> <value>`	Set a config value. Valid keys: `name`, `email`
`show`	Show current DID, name, and email

Example

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

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.

Example

kutl log .kutl/docs/notes.dt

Files and directories

Path	Purpose
`~/.kutl/identity`	DID keypair (ed25519)
`~/.kutl/credentials`	Stored auth tokens (per-relay)
`~/.kutl/daemon.pid`	Running daemon PID
`~/.kutl/logs/daemon.log`	Daemon output log
`.kutlspace`	Team-wide space config (safe to commit)
`.kutl/space.json`	Per-installation runtime config (space ID, relay URL)
`.kutl/docs/`	Document storage (.dt files)