FinLab 的指令列介面（CLI）
FinLab CLI 目前透過 python -m finlab 使用，支援帳號登入、憑證匯出、登入狀態檢查、舊 token 遷移、AI 助理，以及雲端策略部署與排程。
尚在測試
目前此功能為 Alpha 階段，可能會有錯誤或不穩定的情況。請小心使用。 如有任何問題，請至 Discord 上提出問題，我們將盡快來修正。
快速設定
安裝或更新 FinLab：
登入 FinLab 帳號：
查看登入狀態：
身份驗證與憑證
登入
開啟瀏覽器完成登入，並把登入憑證儲存在本機。
登出
清除本機憑證，並嘗試移除伺服器端 session。
查看狀態
顯示目前本機 session、API key 是否設定、方案名稱，以及伺服器端 active sessions。
匯出憑證
在 headless 或雲端環境使用時，可以匯出目前登入憑證。
輸出 shell export 指令：
遷移舊 token
查看從舊版 FINLAB_API_TOKEN 遷移到新版登入系統的指引。
AI 助理
在終端機直接問 FinLab AI 助理：套件用法、回測報錯、資料口徑、帳號與方案。對話與網站客服共用同一份紀錄與每月 200 則提問額度（台灣時間每月 1 日 00:00 重置），使用前需要先登入。
問一個問題，回覆出現前會持續等候：
把錯誤訊息或程式一起送出：
不帶問題就進入對話模式，可以直接貼上多行內容，輸入 exit 離開：
按 Ctrl+C 只會停止等候，提問仍會處理。查看最近一則問答，還在處理就繼續等候：
列出最近 10 則提問，或指定筆數；清單包含提問 ID、建立時間、狀態與題目摘要，依時間由新到舊排列：
用清單中的 ID 讀取指定提問與所有回覆，包含事後追加的案件進度通知。--history 與 --show 讀取當下紀錄，不等候處理完成；查詢只限目前登入的帳號：
加上 --json 可讓自己的 agent 解析結果：
python -m finlab ai --history 50 --json
python -m finlab ai --show <提問ID> --json
python -m finlab ai --last --json
python -m finlab ai "我先前回報的問題目前處理到哪裡？" --json
--history --json 輸出 {"messages": [...]}；其他模式輸出一則完整提問物件，含 id、text、status、createdAt、updatedAt 與 replies 陣列。JSON 保留完整題目與全部回覆。送出問題與 --last 會等候完成後才輸出一個 JSON 物件，進度提示寫到 stderr；請勿將 stderr 合併到 stdout。送出問題仍適用每月 200 則與至少 10 秒的間隔限制。
送出問題與 --last 的結束碼為 0（已回覆）、1（失敗或取消）、130（停止等候）。--history 與 --show 成功讀取時回傳 0，物件的 status 表示提問是否仍在處理。API 錯誤、筆數不大於 0，或未指定查詢與問題時，在 JSON 模式輸出 {"error": "...", "httpStatus": 404}（數字依錯誤而異），結束碼為 1。參數語法錯誤（如 --history abc、--show 未給 ID，或同時指定多種查詢）由 argparse 在 stderr 顯示用法，stdout 不輸出 JSON，結束碼為 2；Ctrl+C 輸出 status: "interrupted"，提問仍會處理。--json 須搭配問題或查詢選項，不用於互動對話。
助理只回答 FinLab 相關問題。提醒後仍重複送出與 FinLab 無關或無意義的內容，或送出惡意內容，帳號會被停用 AI 助理。
自動更新雲端策略
使用 FinLab CLI 可以把策略部署到雲端，設定每日自動執行時間，也可以手動觸發執行、查看執行紀錄與本月用量。
使用前準備
請先登入 FinLab 帳號：
雲端策略程式碼會在獨立容器中執行，容器內已預裝 FinLab SDK。策略 ID 必須以英文字母或數字開頭，只能包含英文字母、數字、.、_、-，最長 64 個字元。排程時間使用 HH:MM 格式，時區為 Asia/Taipei。
方案、額度與 tier
雲端策略執行會依方案限制可用 tier 與策略數量。可以用 python -m finlab cloud status 查看目前帳號允許使用的 tier 與本月執行次數。
方案限制
| 方案 | 可部署策略數 | 預設 tier | 可用 tier |
|---|---|---|---|
| Free | 0 | 無 | 無 |
| VIP | 3 | s |
s |
| AI | 5 | m |
m, l |
| AI MAX | 10 | s |
s, m, l, xl |
如果部署時沒有指定 --tier，新策略會使用帳號方案的預設 tier；更新既有策略時，若該策略已經有 tier，則會保留原本設定。Free 使用者不能部署雲端策略。
Tier 規格
| Tier | CPU | 記憶體 | 最長執行時間 | 併發 |
|---|---|---|---|---|
s |
1 | 4 GiB | 300 秒 | 30 |
m |
2 | 4 GiB | 180 秒 | 1 |
l |
4 | 16 GiB | 300 秒 | 1 |
xl |
8 | 32 GiB | 600 秒 | 1 |
查看策略清單
列出目前登入帳號的雲端策略：
最多列出 500 策略：
查看策略內容
取得單一策略的中繼資料。Inline 策略會顯示程式碼；zip 策略只會顯示中繼資料和進入點檔案，原始碼仍保存在雲端儲存空間。
只輸出 inline 策略程式碼，適合重新導向到檔案或搭配其他工具處理：
部署策略
可以部署單一 Python 檔，也可以部署 zip 壓縮檔形式的多檔案策略。
部署單一 Python 檔：
部署並設定每日自動執行時間：
部署並加入參賽：
python -m finlab cloud deploy my-strategy --code strategy.py --time 09:30 --contest --contest-alias TeamA
部署多檔案策略：
--code 和 --zip 只能擇一使用。Inline 程式碼上限為 256 KiB；zip 壓縮檔上限為 5 MiB，解壓後上限為 50 MiB，最多 100 個檔案。
可用選項：
| 名稱 | 描述 | 預設 |
|---|---|---|
--code |
要部署的單一 Python 策略檔 | None |
--zip |
要部署的 zip 壓縮檔，適合多檔案策略 | None |
--entry-script |
zip 內的 Python 進入點，例如 main.py；使用 --zip 時必填 |
None |
--time |
每日自動執行時間，格式為 HH:MM；省略時保留既有排程 |
None |
--tier |
執行規格，可用 s、m、l、xl，依方案權限限制 |
帳號預設 |
--contest |
將策略加入參賽；只有排程執行會被納入參賽計算 | None |
--no-contest |
將策略退出參賽；後端目前不支援退出後重新加入 | None |
--contest-alias |
公開排行榜顯示名稱，最長 64 個字元 | None |
參賽策略需要在排程執行時產生並上傳回測報告，例如使用 sim(..., upload=True)。手動執行 cloud run 不會納入參賽計算。
手動執行
立即觸發一次執行。策略必須已部署；同一策略的手動觸發限制為每小時 5 次。
也可以只針對這次手動執行覆寫規格：
查看執行紀錄
查看策略近期執行紀錄，包含狀態、執行時間和費用。狀態可能為 queued、running、success、error、timeout、quota_exceeded。
限制列出的紀錄數量，並顯示後端保留的 stdout、stderr 和錯誤訊息：
設定執行頻率
全部以台北時區執行，不自動判斷休市日；每月不存在的日期會跳過。未指定頻率時，新排程每日執行，既有排程保留頻率。
python -m finlab cloud schedule set my-strat 09:00 --frequency weekly --days-of-week 1,5
python -m finlab cloud schedule set my-strat 09:00 --frequency monthly --day-of-month 31
python -m finlab cloud schedule set my-strat --frequency custom --cron '0 9 * * 1-5'
python -m finlab cloud deploy my-strat --code strategy.py --time 09:00 --frequency weekly --days-of-week 1,5
星期使用 0（週日）到 6（週六）。Cron 使用五欄數字：分、時、日、月、星期，支援 *、逗號、範圍與步長；同時指定日期與星期時，任一符合就執行。
設定每日自動執行時間：
移除每日排程：
查看本月額度
查看本月雲端執行使用量、允許使用的 tier 和執行次數：
查詢指定月份：
刪除策略
刪除策略、中繼資料、程式碼和排程。執行紀錄會保留。
略過刪除確認提示：