# CLI 指令

所有 `kura` 子指令、參數，以及它們對磁碟或執行中 daemon 造成的變更。

## 指令

| 指令 | 效果 |
|---|---|
| `kura` | 在背景啟動 daemon 並印出 URL |
| `kura add <name>` | 註冊資料庫，建立 inbox 與 `~/Kura_<name>` 捷徑 |
| `kura list` | 以 `name<TAB>createAt` 列出已註冊的資料庫 |
| `kura remove <name>` | 輸入 `yes` 確認後刪除資料庫 |
| `kura edit <old> <new>` | 重新命名資料庫、資料夾與捷徑 |
| `kura stop` | 停止執行中的 daemon |
| `kura port set <port>` | 固定 HTTP 連接埠（1 到 65535）並重啟 daemon |
| `kura port clear` | 下次手動重啟後改回隨機連接埠 |
| `kura remote enable` | 在 `/mcp` 以 HTTP 提供 MCP；會重啟執行中的 daemon |
| `kura remote disable` | 停止提供 `/mcp`（預設）；會重啟執行中的 daemon |
| `kura mcp` | 以 stdio 提供 MCP |
| `kura help`、`-h`、`--help` | 印出用法 |

其他任何第一個參數（包含不帶參數）都會啟動 daemon。

## 資料庫名稱

名稱使用前會先正規化：連續空白換成單一 `_`，因此 `kura add "my notes"` 會註冊 `my_notes` 並建立 `~/Kura_my_notes`。正規化後為空的參數會以 `invalid name` 結束。

| 指令 | 拒絕條件 |
|---|---|
| `add` | 名稱已註冊，或 `~/.config/kuradb/<name>` 已存在 |
| `remove` | 名稱未註冊；提示時輸入 `yes` 以外的內容會印出 `aborted` |
| `edit` | 舊名稱未註冊、新名稱已註冊，或新資料夾已存在；新舊名稱相同時印出 `noop` |

`remove` 會刪除 `~/.config/kuradb/<name>`（含 `data.db`），僅在 `~/Kura_<name>` 為 symlink 時移除它，最後刪除註冊項目。`edit` 會搬移資料夾、替換捷徑並重新命名註冊項目。

## Daemon 控制

| 指令 | 細節 |
|---|---|
| `kura` | 最多等待 10 秒讓 daemon 寫出 `endpoint` 後印出 URL；逾時則以 1 結束並提示查看 `daemon.log` |
| `kura stop` | 送出 `SIGTERM`，每 100 ms 檢查一次、最多 5 秒，之後送出 `SIGKILL`；印出 `stopped kura (PID <n>)` |
| `kura port set` | 把 `port` 存進 `config.json`，停止存活的 daemon，並啟動新的 daemon（原本沒有執行也會啟動） |
| `kura remote enable/disable` | 把 `remote` 存進 `config.json`；只在 daemon 執行中時重啟 |

新資料庫只在 daemon 啟動時載入，`kura add` 後請執行 `kura stop` 再執行 `kura`。

## 結束碼

| 代碼 | 意義 |
|---|---|
| 0 | 成功、`aborted` 或 `noop` |
| 1 | 執行期失敗，例如名稱未註冊、檔案系統錯誤，或 `stop` 時沒有執行中的 daemon |
| 2 | 用法錯誤：缺少參數、名稱不合法或連接埠不合法 |