營運

CLI 指令參考

所有 costaff 子指令一頁看完。生命週期、Agent / 通訊軟體管理、資料庫、診斷、直接互動。

全域

指令	作用
`costaff --help`	列出所有頂層指令。
`costaff <command> --help`	看某個指令的選項與參數。
`costaff --install-completion`	安裝 shell 自動補完。

首次設定

指令	作用
`costaff onboard`	互動式精靈 — 寫 `~/.costaff/costaff/.env`（model、語言、時區、要啟用的 channel）。詳見首次設定。
`costaff bootstrap -k <gemini-key>`	給 CI / 自動化用的非互動式一鍵部署。寫最小 env（Gemini key、model、語言）然後直接接 `costaff start`。沒帶 `-k` 會 fallback 讀 `$GOOGLE_API_KEY`。

生命週期

把整套 stack 拉起來、關掉、看 log。

指令	作用
`costaff start`	先 preflight 驗證 `.env`（model key、DB URI、secret — 致命問題直接中止並印出修法），再分層啟動：Postgres → 已註冊 Agent → Manager → channel。沒 image 會 build。
`costaff start --no-build`	同上但跳過 build（快速重啟）。
`costaff start --no-preflight`	跳過 `.env` preflight 驗證。
`costaff stop`	停所有容器，volume 留著。
`costaff restart`	等同 `stop` + `start`。
`costaff core-rebuild`	重新 build Manager + 核心 MCP server，並 force-recreate，然後讓每個 plugin agent 重連（不然它們連 core 的 MCP session 會 stale）。
`costaff status`	顯示所有服務的容器狀態。
`costaff logs [service]`	看 log（最後 100 行）。沒帶參數就看全部服務。

Agent 管理

加 / 移除 / 重啟 / 調整專家 Agent。完整流程見專家 Agent。

指令	作用
`costaff agent add <name> --github <url>`	Clone 公開 GitHub repo、驗證 manifest、build 並起 Agent。
`costaff agent add <name> --local <path>`	從本地路徑部署 Agent（不 clone）。
`costaff agent add <name> --url <a2a-url>`	註冊遠端 A2A endpoint — 不起本地容器。
`costaff agent add ... -e KEY=VAL`	預先帶 env var（跳過互動式提問）。
`costaff agent add ... --strict`	Manifest 不過完整 Agent Protocol JSON Schema 就拒（預設只 warn）。
`costaff agent add ... --enable-transfer [-y]`	用 `sub_agents` + `transfer_to_agent` 接線而非預設的 `AgentTool`。會讓 Manager 全域進 transfer 模式 — 沒 `-y` 會要求確認。
`costaff agent list`	列出所有已註冊 Agent，含 A2A URL、健康檢查，以及（若有 pin）`Ref` 欄。
`costaff agent restart <name>`	重啟容器，不 rebuild image，快。
`costaff agent rebuild <name>`	Rebuild image 並重啟。改 code 或 env var 後需要。如果這個 agent 是用 `--tag` 加進來的，會走 `git fetch --tags && git checkout <ref>` 維持那個 ref；否則就是 `git pull --ff-only`。
`costaff agent add ... --tag <ref>`	裝的時候 pin 到某個 git tag、branch 或 SHA。Clone 時帶 `--branch <ref>` 與完整 history，ref 寫進 `config.json`。
`costaff agent rebuild ... --tag <ref>`	換 pin（或第一次 pin）。新 ref 會持久化到 `config.json`。
`costaff agent rebuild ... --no-pull`	完全跳過 git — 直接用工作樹現有內容 build（適合你手動改過 `~/.costaff/costaff-agent/<name>/src/` 之後）。
`costaff agent remove <name>`	停掉、移除、unregister。
`costaff agent enable <name>` / `disable <name>`	切換 Manager 要不要派工到該 Agent（不移除）。
`costaff agent model <name>`	查詢或設定某 Agent 的 LLM model。
`costaff agent transfer <name> --enable` / `--disable`	把已有 Agent 在 AgentTool（預設）與 transfer 模式之間切換。
`costaff agent tags <name>`	列出該 Agent repo 可用的 release tag（`--tag` 的候選值）。

restart vs rebuild

restart 用現有 image — 適合清掉卡住的容器。rebuild 在你改了 Agent 程式碼或 .env 時才需要 — 不然新的 code 或 env var 不會生效。

通訊軟體管理

加 / 管理使用者派工入口。完整流程見通訊軟體。

指令	作用
`costaff channel add <name>`	官方 channel 名稱（`webchat`、`telegram`、`discord`、`line`）會自動解析到對應 GitHub repo。
`costaff channel add <name> --github <url>`	Clone 自訂 channel repo 並部署。
`costaff channel add <name> --local <path>`	從本地路徑部署 channel。
`costaff channel add ... -e KEY=VAL`	預先帶 env var（例如 `TELEGRAM_BOT_TOKEN`）。
`costaff channel list`	列出已註冊 channel 與 port、健康狀態，以及（若有 pin）`Ref` 欄。
`costaff channel rebuild <name>`	Rebuild image 並重啟。如果是用 `--tag` 加進來的就停在該 ref；否則 `git pull --ff-only`。
`costaff channel add ... --tag <ref>`	裝的時候 pin 到某個 git tag、branch 或 SHA。
`costaff channel rebuild ... --tag <ref>`	換 pin（或第一次 pin）。
`costaff channel rebuild ... --no-pull`	跳過 git — 用工作樹現有內容 build。
`costaff channel remove <name>`	停掉、移除、unregister。
`costaff channel tags <name>`	列出該 channel repo 可用的 release tag（`--tag` 的候選值）。

資料庫

內建的 Postgres 存 session、project task、identity 表。

指令	作用
`costaff database info`	顯示連線資訊與資料表摘要。
`costaff database backup [output]`	Dump 到檔案（沒帶參數會用預設路徑）。
`costaff database restore <file>`	從備份檔還原。
`costaff database clean`	清空所有 CoStaff 資料表 — 破壞性操作，會先問。

診斷與維運

指令	作用
`costaff doctor`	一鍵診斷 — 檢查 env var、Docker、容器健康、網路、資料庫，結尾列出建議修復步驟並存帶時間戳的報告。請求協助時第一個要跑（並附上）的指令。
`costaff update`	把 `costaff` repo 拉到最新並重新安裝 CLI。
`costaff update --tag <ref>`	把 core 自己 pin 到某個 tag / branch / SHA，然後重新安裝。
`costaff license`	顯示已安裝的 license 與 feature gate 狀態。
`costaff config validate`	檢查 `~/.costaff/costaff/config.json` 是否符合 schema。

直接互動

適合 scripting 或不走 channel 直接看 Manager 行為時用。

指令	作用
`costaff dashboard [--port 8501]`	啟動 host 端的 FastAPI dashboard（跟 Agent 容器分開）。
`costaff chat [app_name]`	跟 Manager 開互動式 REPL（預設 `costaff_agent`）。
`costaff invoke "<prompt>"`	送一個 prompt 給 Manager 並印出回應。

版本 pin

Agent、channel、以及 core 本身都能 pin 到指定的 git tag / branch / SHA。Pin 之後 rebuild 會停在那個 ref，不會自動拉 main 的最新。

# 裝的時候 pin 到指定 tag
costaff agent add ba --github https://github.com/costaff-ai/costaff-agent-business-analysis \
  --tag v0.1.0

costaff channel add telegram --tag v0.1.0
costaff update --tag v0.1.0   # core 也 pin

# 之後的 rebuild 都會停在 pin 的 ref
costaff agent rebuild ba

# 把 pin 換成新版本
costaff agent rebuild ba --tag v0.2.0

# 完全跳過 git — 直接用工作樹現有內容 build
costaff agent rebuild ba --no-pull

# 看現在 pin 到什麼
costaff agent list      # Ref 欄會顯示目前的 ref
costaff channel list

已 pin 的 repo 不要手動 git pull

Agent ref-pinned 之後，在 ~/.costaff/costaff-agent/<name>/src/ 裡手動 git pull 會 detach HEAD，跟下次 rebuild 期望的狀態漂移。要換版本就用 rebuild --tag。

Tag pinning 上線之前就已經註冊的 entry 沒有 ref 欄位，rebuild 還是走 git pull --ff-only 老路，行為不變。

CLI 在硬碟上的位置

路徑	是什麼
`~/.costaff/.venv/bin/costaff`	安裝好的 CLI entry point。
`~/.costaff/costaff/`	CLI 跑的 git checkout。`git pull` + `pip install -e .` 就是 `costaff update` 做的事。
`~/.costaff/costaff/.env`	核心 env：model provider、secret、DB URI。`onboard` 編這個檔。
`~/.costaff/costaff/config.json`	已註冊的 Agent 與 channel。`agent add` / `channel add` 編這個檔。
`~/.costaff/costaff-agent/<name>/`	每個 Agent 的原始碼與 `.env`。
`~/.costaff/costaff-channel/<name>/`	每個 channel 的原始碼與 `.env`。
`~/.costaff/workspace/`	共享 workspace，bind mount 到每個容器的 `/app/data`。

完整移除

# 先全部停掉
costaff stop

# 移除容器、image、docker network
docker compose -f ~/.costaff/costaff/docker-compose.yaml down --rmi local --volumes

# （可選）清掉 Postgres 資料 volume
docker volume rm costaff_postgres_data

# （可選）刪掉安裝目錄與所有資料
rm -rf ~/.costaff

想要完全乾淨，再把 ~/.zshrc / ~/.bashrc 裡的 # CoStaff Agent CLI PATH 那行刪掉。做完就回到安裝前的狀態。