Kimetsu
Kimetsu Network

Reference

kimetsu network commands, flags, and the two MCP tools.

Reference

These commands ship in v2.11.0 prebuilt and npm binaries. A binary without the network cargo feature still accepts kimetsu network status and reports that the network is not compiled in; the other subcommands error. Nothing is listening in that case.

Network state defaults to ~/.kimetsu/network. Override it with --state-dir or $KIMETSU_NETWORK_DIR.

kimetsu network invite

Create a one-person join code. Saves membership if this is a new network. Does not listen.

kimetsu network invite [--name <name>] [--json] [--state-dir <dir>]
FlagDefaultMeaning
--namefriendsName for a new network. Letters, numbers, -, and _. 1–64 characters. Ignored when you are already the founder and are issuing another code
--jsonoffPrint code, group, and listening: false
--state-dir~/.kimetsu/networkWhere network keys live

Only the founder (the person who created the network) can invite. The printed code starts with knet1. and does not include the admin key. Treat it as a bearer credential.

kimetsu network join

Join with a code from invite. Saves membership. Does not listen.

kimetsu network join <code> [--json] [--state-dir <dir>]

Refuse to join if this machine is already on a network (run leave first), if the code is invalid, if it shares more than the repo mount, or if it comes from a newer kimetsu (v is not 1).

kimetsu network status

Show whether this machine is on a network. Does not listen, discover, or contact a relay.

kimetsu network status [--json] [--state-dir <dir>]

--json prints compiled, joined, listening (always false for this command), and when joined: group, role, generation, endpoint_id.

kimetsu network leave

Forget the network on this machine. Does not listen. Removes local network state files. It does not tell other machines that you left.

kimetsu network leave [--state-dir <dir>]

kimetsu network share

Export this repo's memories as a signed pack and wait for a peer to fetch them. Listens until you press Ctrl-C. Only the repo mount is shared. Refuses to start if the security scrub is not clean.

kimetsu network share [--workspace <dir>] [--bind <ip:port>] [--no-mdns] [--map-ports] [--ready-file <file>] [--state-dir <dir>]
FlagDefaultMeaning
--workspacecurrent directoryRepo whose brain to share
--bind(unset)IPv4 socket to bind, for example 127.0.0.1:0
--no-mdnsoffDo not announce this machine on the local network
--map-portsoffAsk the router to open a UDP port (UPnP / NAT-PMP). Off by default
--ready-file(unset)After the socket is up, write {endpoint_id, dial, peer, digest, listening} here
--state-dir~/.kimetsu/networkWhere network keys live

share prints a peer: <endpoint-id>@host:port line for the other machine to pass to request. Relay is always disabled.

kimetsu network request

Fetch repo memories a peer is sharing right now. Verifies the signature before any write. An unknown signer is quarantined. Listens only while this command runs.

kimetsu network request [--peer <endpoint-id>@host:port] [--workspace <dir>] [--bind <ip:port>] [--no-mdns] [--map-ports] [--json] [--state-dir <dir>]
FlagDefaultMeaning
--peer(unset)Sharer's endpoint-id@host:port line. Without it, local discovery of roster members is used
--workspacecurrent directoryRepo that receives the pack
--bind(unset)IPv4 socket to bind, for example 127.0.0.1:0
--no-mdnsoffDo not look for peers on the local network. Then --peer is required
--map-portsoffAsk the router to open a UDP port (UPnP / NAT-PMP)
--jsonoffPrint import counts (verified, digest, imported, deduped, quarantined, superseded, listening: false)
--state-dir~/.kimetsu/networkWhere network keys live

You must have joined first. This machine has to be on the same network as the sharer.

MCP tools

These tools are registered only in network-enabled builds, when you run kimetsu mcp serve.

kimetsu_network_status

Whether this machine has joined a Kimetsu peer network. Does not listen, discover peers, or contact a relay. No arguments. Sharing stays a terminal command: kimetsu network share.

kimetsu_network_request

Fetch repo memories a peer is sharing. Verifies the pack signature before any write. Refuses packs that are not scoped to repo. Does nothing and opens no socket when this machine has not joined.

ArgumentDefaultMeaning
peer(unset)endpoint-id@host:port from kimetsu network share
discoverfalseLook for roster peers on the local network
map_portsfalseAsk the router to open a UDP port

You must pass peer or discover: true. Otherwise the tool refuses and contacts nothing.

See Connect your tools for host setup.

On this page