# CLI 指令

## 頂層分派

`agen` 解析 `os.Args[1]` 並分派到下列子指令之一。不帶子指令時 attach TUI（若無 daemon 執行中則 fork-exec 一個）；stdin 非 TTY 時則改為透過標準輸入輸出提供 MCP JSON-RPC 服務。v1.2.0 起 TUI 不再自行執行 agent：所有請求都經 `~/.config/agenvoy/daemon.sock` 送給 daemon，daemon 未執行時每 5 秒重新連線。

```bash
agen                       # Attach TUI；無 daemon 時自動啟動
agen stop                  # 停止 daemon
agen update                # 下載最新 release 並重新編譯
agen --daemon              # 直接啟動 daemon
agen -p <prompt> [flags]   # 經 POST /v1/send 送出單次 prompt（v1.3.9）
```

以上即為全部介面。其餘不以 `-` 開頭的第一個參數會印出 usage 並以 1 結束。單次執行的 `agen cli <input>` / `agen run <input>` 已移除；v1.3.9 起改由 `agen -p` 以 `POST /v1/send` 的輕量用戶端承接這個用途。

## 單次執行（`agen -p`）

`agen -p <prompt>` 必要時啟動 daemon（最多等 30 秒直到 port 可連線），以新的 `temp-` session 對 `POST /v1/send` 送出一次請求並印出回覆。`-p` 為空時從 stdin 讀取；`-p <prompt>` 之後若有多餘參數會直接報錯（exit 2），prompt 請加引號。它一律帶 `enable_edit` 與 `enable_sandbox`，因此以 API auto mode 執行，不會跳出確認。

| 旗標 | `/v1/send` 欄位 | 預設 |
|---|---|---|
| `-m`, `--model` | `model` | `auto` |
| `-r`, `--reasoning` | `reasoning` | `medium` |
| `--stream` | `stream` | 關閉 |
| `--work-dir` | `work_dir` | 當前目錄；相對路徑以此解析 |
| `--allow-edit` | `enable_edit` | 關閉（唯讀） |
| `--skip-sandbox` | `enable_sandbox`（取反） | 關閉（留在沙箱） |

`--skip-sandbox` 具危險性：該次執行可不經確認存取 `$HOME` 外路徑、`sudo` 與 `sandbox: false`。v1.3.11 起說明文字將其標為 `DANGEROUS` 且僅限本機，daemon 也只接受來自 loopback 連線的 `enable_sandbox:false`（否則回 403）。

加上 `--stream` 時，model、工具與 thinking 以 `⏵ Model(...)`、`⏵ <Tool>(...)`、`✻ ...` 印到 stderr，回覆串流到 stdout。錯誤 exit 1，取消（Ctrl+C）exit 130，執行結束前串流就中斷也 exit 1。取消只停止用戶端，daemon 端仍會把任務跑完。

`agen --enable-claude-code` 已移除於 v1.2.3：只要 daemon 在 `PATH` 上找得到 `claude` binary，`claude-code` 供應商就會啟用。

短暫存在的 `agen startup <enable|disable>` 子指令已移除；開機自動啟動請在 TUI `/config` 的 **Startup on login** 切換。

模型、session 與 MCP 管理位於 TUI（`/model`、`/session`、`/new`、`/mcp`）、`http://127.0.0.1:17989` 的 web 儀表板，以及本機 HTTP API——不再有 `agen model` / `agen session` / `agen mcp` 子指令。

### `agen stop`

對所有執行中的 `agen --daemon` 行程送 SIGTERM（由行程清單找出，另加 runtime 紀錄中的那一個），而非只停紀錄中的那一個，接著清除 runtime 紀錄。無存活行程時印出 `No daemon running.` 並以 0 結束；PID 紀錄過期時直接清除而非嘗試 kill。

### `agen update`

一律覆寫式更新到最新 release。下載 `https://agenvoy.com/scripts/update.sh` 至系統暫存目錄（`$TMPDIR`）的 `agenvoy-update-*.sh`，以 `bash` 執行，完成後移除暫存檔（SIGINT / SIGTERM 亦會清理）。執行中的 daemon 仍持有舊 binary inode——請 `agen stop` 後重新接上以載入新版。

## 模式

在 TUI 以 `Shift+Tab` 切換 auto 模式（`safe` ↔ `auto`）、`Shift+F` 切換 fast 模式、`Shift+G` 切換 `CLAUDE.md` / `AGENTS.md` 注入（v1.2.0），`Shift+P` 設定工作目錄（v1.3.0）。以 `!` 開頭的輸入會在該目錄以 shell 指令執行，結果交給 agent（v1.3.0）。Auto 模式為 session 區域性設定：TUI 啟動時工作目錄為 `$HOME` 底下的子目錄（不是 `$HOME` 本身，也非禁止或敏感路徑）即為 `auto`，否則為 `safe`。`POST /v1/send` 沒有 `allow_all` 欄位；auto 模式僅是 TUI 切換。完整快捷鍵與斜線指令清單見 TUI 指南。

## 設定

Runtime 限制位於 `~/.config/agenvoy/config.json` 的 `limits`；沒有環境變數覆寫。詳見設定檔頁。