# CLI Reference

Every `kura` subcommand, its arguments, and what it changes on disk or in the running daemon.

## Commands

| Command | Effect |
|---|---|
| `kura` | Start the daemon in the background and print its URL |
| `kura add <name>` | Register a database and create its inbox and `~/Kura_<name>` link |
| `kura list` | Print registered databases as `name<TAB>createAt` |
| `kura remove <name>` | Delete a database after typing `yes` |
| `kura edit <old> <new>` | Rename a database, its folder, and its link |
| `kura stop` | Stop the running daemon |
| `kura port set <port>` | Pin the HTTP port (1 to 65535) and restart the daemon |
| `kura port clear` | Return to a random port on the next manual restart |
| `kura remote enable` | Serve MCP over HTTP at `/mcp`; restarts a running daemon |
| `kura remote disable` | Stop serving `/mcp` (default); restarts a running daemon |
| `kura mcp` | Serve MCP over stdio |
| `kura help`, `-h`, `--help` | Print usage |

Any other first argument, including none, starts the daemon.

## Database Names

Names are normalized before use: runs of whitespace become a single `_`, so `kura add "my notes"` registers `my_notes` and links `~/Kura_my_notes`. An argument that is empty after normalization exits with `invalid name`.

| Command | Refuses when |
|---|---|
| `add` | The name is already registered, or `~/.config/kuradb/<name>` already exists |
| `remove` | The name is not registered; anything other than `yes` at the prompt prints `aborted` |
| `edit` | The old name is not registered, the new name is registered, or the new folder exists; identical names print `noop` |

`remove` deletes `~/.config/kuradb/<name>` including `data.db`, removes `~/Kura_<name>` only if it is a symlink, then drops the registry entry. `edit` moves the folder, replaces the link, and renames the registry entry.

## Daemon Control

| Command | Detail |
|---|---|
| `kura` | Waits up to 10 seconds for the daemon to write `endpoint`, then prints the URL; otherwise exits 1 and points to `daemon.log` |
| `kura stop` | Sends `SIGTERM`, polls every 100 ms for up to 5 seconds, then sends `SIGKILL`; prints `stopped kura (PID <n>)` |
| `kura port set` | Saves `port` in `config.json`, stops a live daemon, and starts a new one even if none was running |
| `kura remote enable/disable` | Saves `remote` in `config.json`; restarts only when a daemon is running |

New databases are loaded only at daemon startup, so run `kura stop` then `kura` after `kura add`.

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success, `aborted`, or `noop` |
| 1 | Runtime failure, such as an unregistered name, a filesystem error, or no running daemon for `stop` |
| 2 | Usage error: missing arguments, invalid name, or an invalid port |