# Fox CLI 安裝指南

> 適用對象：想在命令列使用 `fox` 與 Fox 後端互動的人與 AI agent。
> 命令功能、設計原則與開發計畫見 [README.md](../README.md)。
> 本指南以 macOS／Linux 為主（Windows 差異處另行註記）。

## 一、前置需求

| 項目 | 需求 | 說明 |
|------|------|------|
| Node.js | ≥ 22 | CLI 使用內建 `fetch`，**零執行期相依**（無第三方套件） |
| pnpm | 任意近期版本 | 僅安裝與建置階段需要 |
| git | 任意近期版本 | 取得原始碼 |
| Fox 後端 | 可連線的 API 位址 | 見第四節；本機開發預設 `http://localhost:3000` |

檢查版本：

```bash
node --version   # 應為 v22 以上
pnpm --version
```

沒有 pnpm 時可用 Corepack（Node 內建）或 npm 安裝：

```bash
corepack enable            # 或
npm install -g pnpm
```

> CLI 是純客戶端工具：**不需要** Postgres／MinIO（`docker compose`）或前端，只要網路上連得到後端 API 即可。

## 二、取得與建置

```bash
git clone https://gitea.alterminal.com/alterminal/fox-cli.git
cd fox-cli
pnpm install     # 安裝相依（typescript／@types/node，僅建置需要）
pnpm build       # 以 tsc 編譯到 dist/
```

建置產物 `dist/` 是純 JavaScript，只使用 Node 內建模組，可整個目錄複製到其他有 Node ≥22 的機器直接執行。

## 三、執行方式（擇一）

**1. 倉庫內直接使用**

```bash
node dist/cli.js --help
# 或
pnpm start auth status
```

注意：`pnpm start -- <子命令>` 這種含 `--` 的寫法，在 pnpm 9 會把 `--` 當成參數傳給程式而報「未知命令」——**不要加 `--`**。

**2. 掛上 PATH（推薦）**

```bash
mkdir -p ~/.local/bin
ln -s "$(pwd)/dist/cli.js" ~/.local/bin/fox
# 確認 ~/.local/bin 在 PATH 內（echo $PATH）；沒有就加進 shell 設定檔後重開 shell
fox --help
```

> symlink 指向倉庫內的 `dist/cli.js`；`pnpm build` 之後即是新版（pnpm 不會為倉庫本體建立 bin 連結，掛 PATH 請用 symlink）。

**3. 不建連結，直接以 node 執行**

```bash
node dist/cli.js --help
```

## 四、設定：API 位址與 access token

讀取優先順序（高 → 低）：

1. `--api-url`／`--token` 參數
2. 環境變數 `FOX_API_URL`／`FOX_API_TOKEN`
3. 設定檔 `~/.config/fox/cli.json`
4. `apiUrl` 預設 `http://localhost:3000`（token 無預設）

**環境變數（推薦，適合 agent／CI）**

```bash
export FOX_API_URL="https://api.fox.example.com"
export FOX_API_TOKEN="fpat_…"   # token 值請見下方安全說明
```

**設定檔**

```bash
mkdir -p ~/.config/fox
umask 077
cat > ~/.config/fox/cli.json <<'EOF'
{
  "apiUrl": "https://api.fox.example.com",
  "token": "fpat_…"
}
EOF
chmod 600 ~/.config/fox/cli.json
```

Windows 的對應路徑為 `%USERPROFILE%\.config\fox\cli.json`。

> `--token <value>` 會留在 shell 歷史與 process list，僅供本機快速測試，不建議日常使用。

**取得 access token**：在 Fox 網頁端以自己的帳號建立，或由管理員通過 `POST /access-tokens` 建立。token 以 `fpat_` 開頭，**原始值只在建立當下顯示一次**。之後隨時可用 `fox tokens verify` 確認有效性（過期或撤銷會回 401）。

**安全原則**：token 只存放在環境變數或本機設定檔（權限 600），**絕不寫進 commit、issue、PR 或任何儲存庫內容**。經公開渠道交付時須以收受方公開金鑰加密（組織慣例見 `alterminal/agents` 的 AGENTS.md 2.3）。

## 五、驗證安裝

```bash
fox --help        # 印出命令清單（exit 0）
fox auth status   # 公開端點：查後端登入／SSO 設定
fox tokens verify # 需要 token：有效回 exit 0；缺少或無效回 exit 1 並在 stderr 說明
```

| exit code | 意義 |
|-----------|------|
| 0 | 成功 |
| 1 | 執行失敗（後端 4xx/5xx、網路錯誤、缺 token） |
| 2 | 用法錯誤（缺參數、未知命令） |

stdout 只輸出**單一 JSON**（可直接管給 `jq`），人類可讀訊息一律走 stderr：

```bash
fox novels get my-novel | jq '.title'
```

## 六、更新與解除安裝

```bash
# 更新
cd fox-cli
git pull
pnpm install && pnpm build

# 解除安裝
rm ~/.local/bin/fox        # 若有建連結
rm -rf /path/to/fox-cli    # 倉庫本體
rm ~/.config/fox/cli.json  # 內含 token，一併刪除
```

## 疑難排解

- **`fox: command not found`**：`~/.local/bin` 不在 PATH，或還沒建 symlink（見第三節）。
- **`未知命令：fox --…`**：用了 `pnpm start -- <子命令>` 的寫法；把 `--` 拿掉（見第三節）。
- **`無法連線到 http://localhost:3000`**：後端沒開或位址不對；設定 `FOX_API_URL` 指向正確的 API 位址。
- **`缺少 access token`**：需要授權的命令（如 `tokens verify`）沒有設定 token；見第四節。