kd Command Reference

The non-interactive CLI for scripts and AI agents. All output is JSON.

Model

kd start runs a daemon in the foreground. The daemon holds the connection, the mount, and the session state.

Every other command is a one-shot client. It connects to the daemon over a Unix socket, sends one request, prints one line of JSON, and exits.

The socket path is $KD_SOCKET, or /tmp/kd.sock by default. One daemon per socket. To run two daemons on one machine, see How to run two instances.

Source: cmd/kd/main.go.

Output format

Every command prints exactly one JSON object:

{"ok":true,"data":{...}}
{"ok":false,"error":"..."}

When the daemon is not running, the client prints the error to stderr instead:

{"ok":false,"error":"daemon not running (socket: /tmp/kd.sock)"}

Exit codes

Check the ok field, not the exit code. The exit code is 0 even when a command fails. It is 1 only when the client cannot reach the daemon socket.

kd pull missing-file.txt
# prints {"ok":false,"error":"file not found: missing-file.txt"}
# exit code is 0

kd pull report.pdf ./report.pdf | jq -e '.ok'
# jq -e sets the exit code from the ok field

Commands

Lifecycle

Command	Description
`kd start`	Start the daemon in the foreground. Configure with environment variables before this call. Ctrl-C stops it cleanly.
`kd stop`	Disconnect, unmount, and shut the daemon down. `kd quit` is an alias.
`kd version`	Show version and commit hash.
`kd help`	Show the built-in help. `--help` and `-h` are aliases.

Connection

Command	Description
`kd show [what]`	Show info: `fingerprint`, `ip`, `peer`, `relay`, `status`, `config`, or `all`.
`kd register <fingerprint>`	Register the peer's fingerprint. On a LAN, an `ip:port` address is also accepted.
`kd connect`	Connect to the registered peer. The role is chosen automatically: the lower fingerprint creates the room, the higher one joins.
`kd create`	Create a room and wait for the peer. Use when you control the roles yourself.
`kd join`	Join a room the peer created first.
`kd discover`	Scan the local network. Returns your session name and the peers found: `{"my_name":"...","peers":[{"name":"...","addr":"..."}]}`. The first call takes about 6 seconds.
`kd connect-lan <peer-name> <peer-addr>`	Connect to a peer found by `discover`, with the role chosen automatically.
`kd disconnect`	Disconnect and reset the session. Returns a new fingerprint. Saved contacts still reconnect.
`kd status`	Connection status and session info. See Status fields.
`kd peer-info`	Peer details and connection mode.

Files

Command	Description
`kd add <filepath>`	Share a file or directory with the peer.
`kd add-as <path> <remote-name>`	Share with a custom remote name.
`kd unshare <filename>`	Stop sharing a file. The file stays on disk.
`kd list`	List all shared files, local and remote.
`kd pull <name> [local-path]`	Download a remote file. Without `local-path` it lands in the save path.
`kd cancel-download <name>`	Pause an active download. Partial data is kept. Run `kd pull` again to resume.
`kd progress <name>`	Download progress, 0-100.
`kd file-size <name>`	Get a remote file's size.
`kd local-file-path <name>`	Get the real local path of a file.
`kd bench-pull <name> [path]`	Pull a file, report MB/s, then delete the local copy.

Contacts

Command	Description
`kd contacts`	List saved contacts with online status.
`kd add-contact <name> <fingerprint>`	Save a contact.
`kd remove-contact <fingerprint>`	Remove a saved contact.
`kd quick-connect <fingerprint>`	Connect to a saved contact. No new fingerprint exchange.
`kd save-contact <name>`	Save the currently connected peer as a contact.

Modes and diagnostics

Command	Description
`kd incognito [on\|off]`	Query or toggle incognito mode. Incognito uses ephemeral keys and writes nothing to disk. Interrupted downloads do not resume across a disconnect in this mode.
`kd poll-event`	Pop the next event from the event queue. See Events.
`kd export-logs [dest]`	Export a sanitized copy of the log. `sanitize-logs` is an alias.
`kd config-path`	Show the config file path.
`kd log-path`	Show the log file path.

Events

kd poll-event is non-blocking. It returns {"event":""} when the queue is empty. The queue holds 64 events. On overflow, the oldest event is dropped. Poll faster than events arrive.

Events the daemon emits:

Event	Meaning
`connect_status:Waiting for peer...`	Room created, waiting for the peer.
`connect_status:peer_not_ready`	Join attempted before the peer created the room.
`connect_status:Waiting for peer to connect...`	Handshake in progress.
`connection_mode:lan` / `direct` / `bridge`	Connected; which network path is in use.
`peer_disconnected:health_timeout`	The peer stopped answering heartbeats.
`reconnecting:`	Automatic reconnection started.
`reconnected:`	Reconnection succeeded. Shared files are restored, partial downloads resume.
`resuming_downloads:<N>`	N interrupted downloads resume automatically.
`gave_up:`	Reconnection stopped after repeated failures.

Status fields

kd status returns these fields:

Field	Values
`running`	true / false
`connection_status`	`healthy`, `degraded`, `disconnected`, `unknown`
`connection_mode`	`lan`, `direct`, `bridge`
`fingerprint`, `peer_fingerprint`	Your identity and the peer's.
`ip`, `peer_ip`	Advertised addresses.
`relay`, `fuse`, `mount_path`, `save_path`	Session configuration in effect.
`local_files`, `remote_files`	Counts of shared files on each side.
`writer_epoch`	Internal session counter.

Environment variables

Set these before kd start. They have no effect on client commands.

Variable	Default	Meaning
`KD_RELAY`	`https://keibidroprelay.keibisoft.com/`	Relay URL.
`KD_INBOUND_PORT`	`26431`	Listen port. Must be in 26000-27000.
`KD_OUTBOUND_PORT`	`26432`	Outbound port. Must be in 26000-27000.
`KD_SAVE_PATH`	`~/KeibiDrop/Received`	Where received files are saved.
`KD_MOUNT_PATH`	`~/KeibiDrop/Mount`	FUSE mount point.
`KD_NO_FUSE`	false	Disable the FUSE mount.
`KD_LOG_FILE`	per platform	Log file path. See Files and folders.
`KD_INCOGNITO`	false	Ephemeral keys, nothing written to disk.
`KD_PASSPHRASE_PROTECT`	false	Ask for a passphrase to encrypt the identity.
`KD_SOCKET`	`/tmp/kd.sock`	Daemon socket path.
`KD_LOCAL`	unset	Any non-empty value starts the daemon in LAN mode.
`KEIBIDROP_CONFIG_DIR`	`~/.config/keibidrop`	Move the whole config directory. Use for a second instance.

Boolean values: 0, false, no, and off mean false. Any other non-empty value means true. KD_NO_FUSE=false keeps FUSE on.

The full option list, config file keys, and precedence rules are in the configuration reference.

keibidrop-cli reference →