# KeibiDrop Agent CLI Guide (kd)

`kd` is a non-interactive CLI for KeibiDrop. It runs as a background daemon and accepts one-shot commands via Unix socket. Designed for AI agents (Claude Code, etc.) to share files between systems programmatically.

## Architecture

`kd start` runs a foreground daemon that holds the KeibiDrop instance. All other commands are thin clients that connect to the daemon via Unix socket, send a JSON request, and print the JSON response.

The daemon dispatches commands directly to Go functions -- no HTTP server, no REST API, just function calls over IPC.

## Quick Start

### Build

```bash
make build-kd
```

### Start the daemon

```bash
# No-FUSE mode
KD_SAVE_PATH=./received KD_NO_FUSE=1 ./kd start

# FUSE mode (recommended for agents)
KD_SAVE_PATH=./saved KD_MOUNT_PATH=./mount ./kd start
```

The daemon runs in the foreground and prints its fingerprint as JSON on startup.

### Connect to a peer

```bash
./kd show fingerprint              # get your fingerprint
./kd register <peer-fingerprint>   # register peer
./kd create                        # or "./kd join"
```

### Share files (FUSE mode)

After connecting, `kd status` returns the `mount_path`. Use it as a live synced folder:

```bash
ls ./mount/                        # list peer's files
cat ./mount/config.yaml            # read a remote file
cp ./myfile.pdf ./mount/           # share a file
```

### Share files (no-FUSE mode)

```bash
./kd add ./myfile.pdf              # share a file
./kd list                          # see all files
./kd pull report.pdf ./report.pdf  # download from peer
```

## JSON Output Format

Every command returns a single JSON line:

```json
{"ok":true,"data":{"fingerprint":"abc123..."}}
{"ok":false,"error":"daemon not running (socket: /tmp/kd.sock)"}
```

- `ok: true` -- command succeeded, result in `data`
- `ok: false` -- command failed, reason in `error`
- Exit code 0 on success, 1 on failure

## Command Reference

| Command | Description |
|---|---|
| `kd start` | Start daemon (foreground, prints fingerprint) |
| `kd stop` | Stop daemon |
| `kd show fingerprint` | Show your fingerprint |
| `kd show status` | Show connection status |
| `kd register <fp>` | Register peer fingerprint |
| `kd create` | Create room (blocks until peer joins) |
| `kd join` | Join room (blocks until connected) |
| `kd add <path>` | Share a file (no-FUSE mode) |
| `kd list` | List all files (local + remote) |
| `kd pull <name> [path]` | Download remote file (no-FUSE mode) |
| `kd status` | Full status (connection, files, mount path) |
| `kd disconnect` | Disconnect and rotate keys |
| `kd help` | Show help text |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| KD_RELAY | Relay server URL | https://keibidroprelay.keibisoft.com |
| KD_INBOUND_PORT | TCP listen port (26000-27000) | 26431 |
| KD_OUTBOUND_PORT | TCP outbound port (26000-27000) | 26432 |
| KD_SAVE_PATH | Where to save received files | (required) |
| KD_MOUNT_PATH | FUSE mount point directory | (enables FUSE) |
| KD_NO_FUSE | Disable FUSE (any value) | (unset) |
| KD_LOG_FILE | Log file path | stderr |
| KD_SOCKET | Unix socket path | /tmp/kd.sock |

## Running Multiple Instances

Each instance needs unique ports and socket:

```bash
# Alice
KD_INBOUND_PORT=26001 KD_OUTBOUND_PORT=26002 \
  KD_SOCKET=/tmp/kd-alice.sock ./kd start

# Bob
KD_INBOUND_PORT=26003 KD_OUTBOUND_PORT=26004 \
  KD_SOCKET=/tmp/kd-bob.sock ./kd start
```

Prefix all client commands with the socket:

```bash
KD_SOCKET=/tmp/kd-alice.sock ./kd show fingerprint
KD_SOCKET=/tmp/kd-bob.sock ./kd register <alice-fp>
```

## For Agent Developers

1. Start the daemon with FUSE enabled (`KD_MOUNT_PATH=./mount`). This is the recommended mode.
2. Parse all output as JSON. Check the `ok` field.
3. `kd create` and `kd join` are blocking. Run them in the background or with a timeout.
4. After connecting, use `kd status` to get the `mount_path`. This is the synced folder.
5. The `mount_path` is a live, bidirectional view of shared files. Read remote files and write local files directly. No need for `kd add` or `kd pull`.
6. Each daemon instance needs unique ports and a unique `KD_SOCKET`.

## Security Notes

- No login or accounts. Identity is an ephemeral cryptographic fingerprint.
- Keys rotate on every disconnect. Identity disappears after the session.
- All traffic is encrypted end-to-end (ChaCha20-Poly1305).
- The relay only sees encrypted blobs.
- Fingerprint exchange is the trust anchor. Send it via a secure channel.

## Related Pages

- [KeibiDrop Overview](keibidrop.md) -- What it is and why
- [Quickstart Guide](keibidrop-quickstart.md) -- Build and run in 5 minutes
- [API Reference](keibidrop-api-reference.md) -- Detailed JSON output examples
- [FUSE vs No-FUSE](keibidrop-fuse-vs-nofuse.md) -- Choosing the right mode
- [Security Model](keibidrop-security.md) -- Full cryptographic details
- [WAW Index](index.md) -- All pages