feastalytics/cli

Feast CLI

從終端機驅動 Feastalytics 平台。feast CLI 公開了與應用程式內 AI 代理相同的工具表面（行銷活動、自動化、優惠、漏斗、會員計畫），以純命令形式代表已登入使用者向正式 API 發送請求。

CLI 是 哪些 工具存在以及 它們接受什麼 的唯一真相來源 — 請務必在執行時探索它們，而非假設，因為隨著新端點被標記，工具集會持續成長。你的任務是選擇正確的工具，將其範圍限制在正確的組織，並提供有效的輸入。

先決條件

feast CLI 必須已安裝並位於 PATH：

npm install -g @feastalytics/cli    # 或使用 ad-hoc 執行：npx @feastalytics/cli <command>

驗證一次即可 — Token 會快取在 ~/.config/feast-cli/credentials.json 中並自動重新整理：

feast login                        # 開啟瀏覽器進行授權（預設）
feast login --password [username]  # 無頭 / CI：使用者名稱 + 密碼提示，無瀏覽器

如果命令回報你未登入或工作階段已過期，請重新執行 feast login。

保持最新

CLI 和此技能都不會自動更新。當命令在 stderr 上列印更新通知時：

Update available: feast 0.1.1 → 0.2.0

請同時更新兩者，然後用一行告知使用者你已完成：

npm install -g @feastalytics/cli@latest      # 僅在 `feast` 已透過全域安裝存在於 PATH 時
npx skills add feastalytics/cli -g -a '*' -y # 從儲存庫重新整理此技能

如果你一直透過 npx 而非全域安裝來呼叫 CLI，請跳過 npm install -g，並在對話的其餘部分改用 npx @feastalytics/cli@latest <command> — 否則 npx 會重複使用快取的副本。

每當更新 CLI 時也請更新此技能：兩者從同一個儲存庫出貨，但觸發時機不同，因此新的 CLI 版本通常意味著此技能的指導也已過時。如果全域安裝因權限問題失敗，請不要用 sudo 重試 — 告知使用者並退回到 npx @feastalytics/cli@latest。

核心循環：探索 → 描述 → 呼叫

請不要猜測工具名稱或輸入格式。內省即時 CLI：

feast tools                 # 列出每個可用的工具、其領域，以及是否會變更資料
feast describe <tool>       # 某個工具的完整描述 + 輸入 JSON 結構
feast call <tool> --org <organizationId> --input '<json>'

在呼叫不熟悉的工具前，務必先 describe 它 — 結構會告訴你確切的必要欄位，CLI 會在發送任何內容前根據此結構在本機驗證你的 --input，因此錯誤的酬載會以清晰的訊息快速失敗，而非令人困惑的伺服器錯誤。

組織：絕不讓 API 猜測

大多數工具作用於一個組織。使用者通常屬於多個組織，因此你目標是哪個組織很重要，且必須明確指定。

feast whoami                # 顯示已登入的使用者以及他們可以操作的所有組織（含名稱）

使用 --org <organizationId> 傳遞目標組織：

• 如果使用者指名了一個組織，請用 feast whoami 將其解析為 ID，然後傳遞該 ID。
• 如果使用者只屬於一個組織，CLI 會自動使用該組織 — 不需要標記。
• 如果他們屬於多個組織而你省略了 --org，CLI 會拒絕並列出這些組織，而非默默地選一個。這是刻意的：作用於錯誤的組織比停下來詢問更糟。發生這種情況時，請向使用者呈現清單並確認他們指的是哪一個。

讀取 vs. 寫入

查詢工具（列出、描述、讀取）是安全且唯讀的。變更工具（建立、更新、複製、刪除、套用）會修改正式資料。

• 變更操作需要明確的 --org。
• 在執行之前，CLI 會在伺服器端解析組織並列印其名稱，因此錯誤的 --org 會顯示為錯誤的餐廳而非不透明的 ID。請仔細閱讀那行輸出。
• 沒有確認提示。 變更操作在你呼叫它的那一刻就會執行。沒有任何東西會詢問兩次，也沒有任何東西可以撤銷。

最後一點對於那些觸及真實世界而不僅僅是資料庫的工具尤為重要。購買電話號碼會向帳戶收費。批准創作者造訪或決定某個投稿會立即向該人發送簡訊，且無法撤回。發布行銷活動會使其上線，而為週期性優惠定價則會建立真實的 Stripe 產品。儲存自動化編輯會改變客人收到的內容。請將這些視為不可逆轉的，並在呼叫之前 先 確認使用者的意圖，因為之後沒有任何關卡。

建議在寫入前先讀取：例如在 updateCampaign 之前先用 listCampaigns 找到正確的 campaignId，或在建立流程前先用 describe/listAutomationFlows。

建構良好的輸入

--input 接受一個 JSON 字串（或更大的酬載使用 --input-file <path>）。根據你從 describe 取得的結構來建構它。當一個工具透過 ID 參考另一個實體（行銷活動 ID、地點 ID、流程 ID）時，請先使用相關的列出/讀取工具查詢該 ID，而非憑空編造。

對於欄位的領域特定含義 — 自動化如何串聯、漏斗畫面包含什麼、優惠如何結構化 — 請在結構本身不足時參閱 references/domains.md 中的指導。

工作流程

許多任務都是多步驟的，並且具有應用程式通常會強制的必要順序。最重要的規則：自動化存在於流程之中 — 在新增自動化之前，務必先找到一個流程（listAutomationFlows）或建立一個流程（createAutomationFlow）；絕不建立孤立的自動化。 相同的「先解析父項/ID，再行動」的模式也重複出現在行銷活動、漏斗和優惠中。

在處理任何多步驟任務之前，請先閱讀其工作流程檔案。 每個檔案都包含必要的呼叫順序以及能讓結果良好而非僅是有效的領域規則 — 這兩者都不在工具結構中。請先閱讀它；不要從工具描述中重建順序。

執行此操作	請閱讀
建立、複製或設定行銷活動；策略待辦事項中的優惠	references/workflows/campaigns.md
任何與自動化相關的操作 — 建立、編輯、模擬、推廣草稿	references/workflows/automations.md
編輯漏斗畫面、套用漏斗範本、暫存新畫面	references/workflows/funnels.md
撰寫 Meta 廣告文案 — 面對客人或招募創作者	references/workflows/facebook.md
創作者來源 — 批准申請者、審查他們的內容、對話	references/workflows/creators.md
會員計畫獎勵；讀取或儲存錢包通行證設定	references/workflows/members-program.md
處理入職任務板；品牌識別	references/workflows/onboarding.md
搜尋客人/會員及其活動	references/workflows/guests.md

當任務跨越它們時，請閱讀多個檔案 — 一個新的行銷活動通常意味著 campaigns.md 加上 automations.md 和 funnels.md。

有些事情是刻意 不公開的：透過簡訊回覆客人或創作者、對活躍會員觸發自動化、獎勵更新/刪除、通行證圖片生成，以及除兩個批准決定之外的創作者管道大部分內容。工作流程檔案會說明哪些。不要為工作流程中 feast tools 未列出的工具捏造呼叫 — 告知使用者該部分尚不可用。

提供你觸及內容的連結

你透過 CLI 完成的工作會以某種形式存在於產品中，而連結是一個成本低廉的好東西 — 所以請大方提供。在你建立、變更或發布某些內容之後，請以簡短的 Markdown 清單結尾：在哪裡可以看到、在哪裡可以編輯、在哪裡可以預覽。不是因為有人必須去檢查你的工作，而是因為打開那個東西通常是下一步。當有人問某個東西在哪裡或如何設定時，請以連結開頭，而不是一步步的點擊指引。

你不知道這些 URL — 在寫出連結之前，請先閱讀 references/links.md。 儀表板的形狀並不是你從此技能其他地方看到的面向客人連結所能推斷出來的，因此看起來明顯正確的 URL 正是需要檢查的情況。錯誤的連結比沒有連結更糟：它看起來有權威性但會回傳 404。

該檔案包含儀表板路徑及其面板和分頁名稱、組織自有子網域上的面向客人頁面、完成漏斗草稿循環的預覽路徑，以及哪些查詢參數實際上會抑制分析，而非僅僅將造訪標記為預覽。

實作範例

使用者：「在我的 Plum Vietnamese 組織的 Plum 地點新增一個滿 5 美元折 5 美元的優惠。」

feast whoami                                    # 找到 Plum Vietnamese 組織 ID
feast describe dfyCreateOffer                    # 了解優惠輸入格式
feast call dfyGetMenuHierarchy --org <orgId> --input '{"locationId":"<id>"}'   # 找到地點/選單 ID
feast call dfyCreateOffer --org <orgId> --input '{ ... }'                       # 建立優惠（先確認）

這個模式可以推廣：識別組織、了解工具、解析任何被參考的 ID，然後行動。

當某件事失敗時

• 「未登入/工作階段已過期」→ feast login（或在無頭/CI 環境中使用 feast login --password [username]）。
• 「你屬於多個組織」→ 使用 --org 選擇一個，並透過 feast whoami 取得 ID。
• 「輸入不符合工具結構」→ 重新閱讀 feast describe <tool> 並修正命名的欄位。
• 你預期的工具未在 feast tools 中列出 → 它可能尚未公開；不要捏造呼叫，請告知使用者。