# KeibiDrop Agent CLI (kd) -- API Reference

Complete reference for the `kd` non-interactive CLI. All commands return JSON.

## Output Format

Success:
```json
{"ok":true,"data":{"key":"value"}}
```

Error:
```json
{"ok":false,"error":"description of what went wrong"}
```

Exit code 0 on success, 1 on failure.

## Commands

### kd start

Start the daemon. Runs in the foreground. All subsequent commands connect to this daemon via Unix socket.

```bash
KD_SAVE_PATH=./saved KD_MOUNT_PATH=./mount ./kd start
```

Output:
```json
{"ok":true,"data":{"fingerprint":"6c_RJID9Tw...","fuse":true,"ip":"2a02:2f00:...","mount_path":"./mount","relay":"https://keibidroprelay.keibisoft.com","save_path":"./saved","socket":"/tmp/kd.sock"}}
```

### kd stop

Shutdown the daemon.

```bash
./kd stop
```

Output:
```json
{"ok":true,"data":{"status":"stopped"}}
```

### kd show fingerprint

Get your fingerprint. Send this to your peer via a secure channel.

```bash
./kd show fingerprint
```

Output:
```json
{"ok":true,"data":{"fingerprint":"6c_RJID9Twnm7o1Q..."}}
```

### kd show ip

Get your IPv6 address.

```bash
./kd show ip
```

### kd show status

Alias for `kd status`.

### kd register \<fingerprint\>

Register a peer's fingerprint. Must be done before create/join.

```bash
./kd register "Y9cykk9ez6blXF_3..."
```

Output:
```json
{"ok":true,"data":{"registered":"Y9cykk9ez6blXF_3..."}}
```

### kd create

Create a room and wait for the peer to join. This command blocks until the peer connects.

```bash
./kd create
```

Output (after peer joins):
```json
{"ok":true,"data":{"peer_ip":"2a02:2f00:...","status":"connected"}}
```

### kd join

Join an existing room. This command blocks until connected.

```bash
./kd join
```

Output:
```json
{"ok":true,"data":{"peer_ip":"2a02:2f00:...","status":"connected"}}
```

### kd status

Full status including connection health, file counts, and paths.

```bash
./kd status
```

Output:
```json
{
  "ok": true,
  "data": {
    "running": true,
    "connection_status": "healthy",
    "fingerprint": "6c_RJID9Tw...",
    "peer_fingerprint": "Y9cykk9ez6...",
    "ip": "2a02:2f00:...",
    "peer_ip": "2a02:2f00:...",
    "relay": "https://keibidroprelay.keibisoft.com",
    "fuse": true,
    "mount_path": "./mount",
    "save_path": "./saved",
    "local_files": 2,
    "remote_files": 3
  }
}
```

### kd add \<path\>

Share a local file with the peer (no-FUSE mode).

```bash
./kd add ./myfile.pdf
```

Output:
```json
{"ok":true,"data":{"added":"./myfile.pdf"}}
```

### kd list

List all files (local and remote).

```bash
./kd list
```

Output:
```json
{
  "ok": true,
  "data": {
    "files": [
      {"name": "myfile.pdf", "size": 1048576, "path": "/tmp/myfile.pdf", "source": "local"},
      {"name": "report.pdf", "size": 204800, "path": "", "source": "remote"}
    ]
  }
}
```

### kd pull \<name\> \[path\]

Download a remote file (no-FUSE mode).

```bash
./kd pull report.pdf ./downloaded-report.pdf
```

Output:
```json
{"ok":true,"data":{"pulled":"report.pdf","to":"./downloaded-report.pdf"}}
```

### kd disconnect

Disconnect from peer. Keys are rotated and a new fingerprint is generated. You can start a new session with a different peer.

```bash
./kd disconnect
```

Output:
```json
{"ok":true,"data":{"new_fingerprint":"5j32NIvH6o...","status":"disconnected"}}
```

### kd help

Print help text (plain text, not JSON).

## Environment Variables

All set before `kd start`:

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

## Error Messages

Common errors and what they mean:

| Error | Cause |
|---|---|
| `daemon not running (socket: /tmp/kd.sock)` | Start the daemon first with `kd start` |
| `no peer fingerprint registered` | Run `kd register <fp>` before create/join |
| `listen tcp6 [::]:26431: bind: address already in use` | Another process uses that port. Set different KD_INBOUND_PORT |
| `no such file or directory` | File path does not exist (for kd add) or remote file name not found (for kd pull) |

## Related Pages

- [KeibiDrop Overview](keibidrop.md) -- What it is and why
- [Quickstart Guide](keibidrop-quickstart.md) -- Build and run in 5 minutes
- [Agent CLI Guide](keibidrop-agent-guide.md) -- Usage patterns for AI agents
- [FUSE vs No-FUSE](keibidrop-fuse-vs-nofuse.md) -- Choosing the right mode
- [Security Model](keibidrop-security.md) -- Cryptographic details
- [WAW Index](index.md) -- All pages