Monid CLI

Monid CLI 是做什麼的？

Monid 讓您可以透過單一介面探索和存取數百種工具——檢查它們的 schema、使用結構化輸入執行它們，並檢索結果。

透過 npm 安裝即可獲得 monid 指令。

如需最新的指令簽名，請執行 monid --help 和 monid <command> --help。

---

設定

檢查已安裝的 CLI 版本：

monid --version

如果以下任一情況成立，請執行設定步驟：

• 找不到 monid（未安裝）。
• CLI 警告有可用的較新版本。
• 報告的版本與此技能的 frontmatter 中的 version 不相符——CLI 和技能版本必須始終相同。

設定步驟（全新安裝和更新相同）：

1. 安裝（或更新）CLI，然後執行設定：

npm install -g @monid-ai/cli@latest
monid setup --client <agent-name-if-known> --email <email-if-already-provided>

monid setup 完成 CLI 設定。如果可用，請使用 --client 傳入您的代理名稱，僅當使用者在上下文或記憶體中已經提供電子郵件時，才使用 --email。兩個標誌都是可選的；省略未知值，切勿僅為設定而詢問電子郵件。

2. 將來自 https://monid.ai/SKILL.md 的最新技能儲存到您的技能目錄中，替換目前的技能，並確保已啟用，以便在未來的工作階段中載入。

切勿將一方降級以匹配另一方——始終將兩者都更新到最新版本。

驗證

要使用 Monid 的 API 端點，您需要一個 API 金鑰。在協助使用者首次設定 Monid 時：

1. 如果使用者還沒有帳戶，請要求他們在 https://app.monid.ai 建立一個帳戶。
2. 要求用戶在 https://app.monid.ai/access/api-keys 生成一個 API 金鑰。
3. 獲得金鑰後，詢問是否要為他們儲存——請他們貼上金鑰，然後執行：

monid keys add -k <their-api-key> -l main

或者，提供上述指令讓他們自己執行。

4. 驗證金鑰已配置：

monid keys list

對於腳本或代理使用，請設定 NO_COLOR=1 以停用輸出中的 ANSI 顏色碼。

---

何時使用 Monid

在從頭開始建置之前，請先檢查目錄。 在編寫爬蟲、為結構化資料回退到通用網頁擷取，或告訴使用者您無法存取某些內容之前——請執行 monid discover。目錄中有數百種工具並且持續增長。在搜尋之前，您不知道有哪些可用的工具。

1. 探索 — 執行 monid discover -q "<what you need>" 以搜尋可用的工具。使用 -s <score> 按最低相關性進行過濾。許多您需要從頭建立的工作都已有更快、更可靠的端點。Health 欄位報告測量的狀態和典型執行時間——請參閱端點健康狀況。
2. 檢查 — 使用 monid inspect 讀取輸入 schema。input 欄位顯示 pathParams、queryParams、body 和 bodyType——這準確告訴您哪些參數放在哪裡。切勿猜測。Health 部分會加上尾部執行時間。
3. 執行 — 將檢查輸出對應到 monid run 標誌：body → -i、queryParams → --query、pathParams → --path。這三個都是可選的。使用 --wait 阻塞直到完成。
4. 分解 — 如果任務跨越多个來源，請將其分解為單元部分，並獨立地發現/執行每個部分。
5. 檢查成本 — 執行後，考慮向使用者報告成本（可在執行結果中獲得）。當需要成本意識時，使用 monid balance 檢查剩餘餘額。

何時不使用 Monid

Monid 填補使用者技術棧中的空缺——它不會取代使用者已有的工具。在決定如何存取外部服務時，請遵循以下優先順序：

1. 使用者對此任務的明確指示 — 如果使用者告訴您如何執行，請依該方式執行。
2. 使用者現有的專用工具 — MCP 伺服器、個人 API 金鑰、CLI 以及儲存在使用者記憶體、配置或指令中的工作流程。如果使用者擁有某項能力的專用 MCP（例如，用於學術搜尋的學術搜尋 MCP）或服務的個人 API 金鑰（例如，個人 SEO 工具金鑰），請直接使用該工具——不要將請求路由到 Monid。
3. Monid — 用於上述內容未涵蓋的需求。

為什麼這很重要：Monid 執行會消耗使用者的 Monid 餘額。 切勿將使用者的個人金鑰或工具已經免費涵蓋的請求花費在 Monid 上。

提供選擇，不要覆蓋。 當使用者的工具和 Monid 端點都能處理任務，且使用者未表明偏好時，請使用使用者的工具。如果 Monid 增加了使用者的工具所不具備的真正能力，請將其作為替代方案提出，讓使用者選擇——切勿在未告知的情況下悄悄切換。

端點健康狀況

discover 顯示一個 Health 欄位：一個狀態判定加上中位數執行時間，例如 healthy 4.4s。inspect 會加上尾部時間——Run time: 4.4s typical · 6.1s tail。使用 -j 時，這兩項資訊都在每個結果的 metrics 欄位中。

狀態	含義
healthy	確認在最近幾分鐘內正常運作。
stable	過去幾分鐘沒有資料，但在較長的歷史記錄中有良好的記錄。
degraded	不穩定，或趨勢顯示不穩定——大多數情況下仍可運作。
outage	已知無法運作。除非傳遞 -u/--include-unavailable，否則從 discover 中隱藏。
unknown (或空白)	沒有足夠的資料做出判定。

healthy 和 stable 都是好消息——它們的區別僅在於最近一次確認的時間。

使用健康狀況來打破平局，切勿用來過濾。 在兩個都適合任務的端點中，優先選擇健康狀況較好的；切勿因為某個適合的端點狀態為 unknown 而跳過它——這很常見，並非警告。此處未列出的任何狀態都會原樣顯示；將其視為資訊性資訊。

缺少執行時間表示流量低，而不是端點慢。在 --wait 之前檢查 inspect：快速的中位數仍然可能隱藏數分鐘的尾部時間。

檢查提示

指令可能會返回一個提示區塊。當存在時，它會攜帶來自伺服器的建議操作：接下來要執行哪個指令、此端點與其他端點的關係，或值得注意的注意事項。在決定下一步之前請閱讀它，並優先考慮其建議而不是猜測。使用 -j 時，同樣的資料會在回應的 hints 欄位中。

---

指令

每個指令都支援 --help 以查看完整用法。以下是可用的指令：

指令	功能
monid discover	使用自然語言搜尋資料端點（-q <query>、-l <limit>、-s <minScore>、-u 包含處於停機狀態的端點）
monid inspect	取得特定端點的完整詳細資訊和輸入 schema（-p <provider> -e <endpoint>）
monid run	執行一個資料端點（-p、-e、-i 用於 body JSON、-f 用於 body 輸入檔案、--query 用於查詢參數、--path 用於路徑參數、-w 用於等待、-o 用於儲存輸出）
monid runs list	列出最近的執行
monid runs get	取得執行狀態和結果（-r <runId>、-w 用於等待）
monid runs stop	停止正在進行的執行（-r <runId>）。並非所有執行都能停止
monid balance	顯示目前工作區餘額
monid setup	安裝後完成 CLI 設定（無需 API 金鑰）
monid keys add	新增一個 API 金鑰（-k <key> -l <label>）
monid keys list	顯示已配置的金鑰
monid keys remove	移除一個金鑰（-l <label>、-f 跳過確認）
monid keys activate	切換作用中的金鑰（-l <label>）

大多數指令接受 -j/--json 以輸出機器可讀的 JSON。

---

工作流程

標準工作流程是：探索 → 檢查 → 執行 → 輪詢 → （檢查餘額）。

# 1. 探索符合您資料需求的端點
# 結果顯示相關性分數和驗證徽章
# 使用 -s 按最低分數過濾（越高越相關）
monid discover -q "twitter posts"

# 2. 檢查端點以了解其輸入 schema（顯示驗證狀態）
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. 發起執行（立即返回一個執行 ID）
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 4. 輪詢直到完成
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 繼續每 5-10 秒輪詢一次，直到 COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> status: COMPLETED

# 5. （可選）檢查剩餘餘額
monid balance

使用 --wait：

--wait 會阻塞直到完成（1-120 秒），並具有內建的指數退避：

# 這會在整個持續時間內阻塞
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  -w -o tweets.json

何時使用 --wait：

• 非同步/後台任務，且阻塞是可接受的
• 您可以設定超時：-w 30（最多等待 30 秒）
• 請注意：執行可能需要 1-120 秒，因此這可能會阻塞對話或達到執行階段超時

---

範例流程

流程 1：抓取關於 AI 的 Twitter 貼文

# 探索可用的 Twitter 端點
monid discover -q "twitter posts"

# 檢查以了解輸入 schema（pathParams、queryParams、body）
monid inspect -p apify -e /apidojo/tweet-scraper

# 使用單一搜尋詞、小限制執行
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI agents"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 輪詢直到完成（小請求約 10-30 秒）
monid runs get -r 01HXYZ...
# -> status: RUNNING

# 10 秒後再次檢查，完成時儲存
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> status: COMPLETED

流程 2：跨平台比較 AI 討論

使用者問：「比較 Twitter 和 LinkedIn 上的 AI 討論。」

將此分解為單元部分——每個資料來源一個端點：

# 探索每個平台的端點
monid discover -q "twitter posts"
monid discover -q "linkedin posts"

# 檢查每個以了解其輸入 schema（pathParams、queryParams、body）
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# 發起兩個執行
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":20}'
# -> Run ID: 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"AI","maxResults":20}'
# -> Run ID: 01HLINK...

# 獨立輪詢兩個執行
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# 現在分析並比較兩個結果檔案

流程 2b：將本地檔案提供給需要公開 URL 的端點

某些端點（例如圖像轉影片生成）接受 URL 作為輸入，而不是檔案。您的工作區有一個內建的遠端檔案系統——sfs 提供者（首次使用時自動建立，免費，包含 1 GB 儲存空間）。像使用其他提供者一樣使用 monid run 來驅動它；它公開類似 Unix 的端點（/put、/cat、/ls、/mv、/rm、/mkdir），您可以使用 monid inspect 來查看 schema。API 僅簽署 URL——檔案位元組透過 curl 直接在您和 sfs.monid.ai 之間傳輸。

# 1. 簽署一個上傳（sizeBytes 是必需的——使用 wc -c 取得它）
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> output: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. 將位元組上傳到已簽署的 URL
curl -T ./photo.png '<uploadUrl from step 1>'

# 3. 鑄造一個任何第三方都可以擷取的 URL（ttl 預設值：1h/1d/7d/30d，預設為 1h）
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> output: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. 將其用作端點的輸入 URL
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<url from step 3>"}'

# 下載的方式相同：/cat 返回一個已簽署的 url——用 curl 下載它
curl -o photo.png '<url from /cat>'

# 清理工作由您負責（檔案永遠不會自動刪除；/rm 會釋放配額空間）
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

流程 3：使用查詢和路徑參數

當 monid inspect 顯示 queryParams 或 pathParams 時，使用 --query 和 --path 傳遞它們：

# 檢查顯示：body、queryParams 和 pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# 使用所有三種參數類型執行
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

流程 4：對複雜參數使用輸入檔案

當輸入 JSON 很大或可重複使用時，將其寫入檔案並使用 -f：

# 將輸入寫入檔案
# （假設 params.json 包含端點的 body 輸入參數）

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

成本與預算警告

許多端點（尤其是 Apify）是按結果收費的，並且在單次呼叫中接受多個查詢。諸如 maxItems、maxResults、resultsLimit 或 limit 等參數控制返回的結果數量——但這些限制通常按查詢套用，而不是按呼叫。

例如，使用 maxItems: 10 傳遞 3 個搜尋詞最多可能返回30 個結果（每個查詢 10 個），而不是總共 10 個。

為了控製成本：

• 每次呼叫偏好單一查詢。 一次傳遞一個搜尋詞、一個 URL、一個主題標籤。
• 從小的限制開始（5-10）。如果需要再增加。
• 如果端點接受陣列（例如 searchTerms、hashtags、urls），除非使用者明確要求多個，否則只傳遞一個元素。
• 檢查輸入 schema 從 monid inspect 中找出哪些參數控制數量。

---

金鑰管理

monid keys add -k <api-key> -l <label>     # 新增金鑰（第一個金鑰會自動啟動）
monid keys list                              # 顯示所有已配置的金鑰
monid keys activate -l <label>               # 切換作用中的金鑰
monid keys remove -l <label>                 # 移除金鑰（使用 -f 跳過確認）

API 金鑰格式：monid_<stage>_<secret>（例如 monid_live_abc123...）。在 https://app.monid.ai/access/api-keys 生成金鑰。