Files

T

alex fcf7680e49 chore: 自 fox monorepo 移出成獨立公開倉庫（fox #49）

- 自 alterminal/fox 的 cli/ 目錄以 git subtree split 移出（保留 git 歷史）。
- package.json：改為獨立專案（移除 private、補 repository／homepage／files、
  增加 packageManager pnpm@9.15.3）。
- README／docs/cli-install.md：路徑與指令改為本倉庫根目錄版型
  （node dist/cli.js、pnpm build；獨立安裝不會建立 node_modules/.bin/fox，
  掛 PATH 改用 symlink）。
- 新增 .gitignore 與 pnpm-lock.yaml。
- 驗證：pnpm install + pnpm build + node dist/cli.js --help（exit 0）、
  未知命令 exit 2。

2026-09-07 21:14:23 +08:00

4.7 KiB

Raw Permalink Blame History

Fox CLI 安裝指南

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

一、前置需求

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

檢查版本：

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

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

corepack enable            # 或
npm install -g pnpm

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

二、取得與建置

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. 倉庫內直接使用

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

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

2. 掛上 PATH（推薦）

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 執行

node dist/cli.js --help

四、設定：API 位址與 access token

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

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

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

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

設定檔

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）。

五、驗證安裝

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：

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

六、更新與解除安裝

# 更新
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；見第四節。

4.7 KiB Raw Permalink Blame History Unescape Escape