在腳本中使用 Figena CLI 輸出

選擇輸出格式，讀取結果欄位，處理結束代碼，並了解重試和逾時規則。

開發者工具Figena CLI4 分鐘閱讀

概述

Figena CLI 的每個指令都回傳相同結構的結果，無論成功還是失敗，腳本都可以依賴同一種格式。本文介紹輸出格式、結果欄位、結束代碼，以及 CLI 如何重試請求。

輸出格式

用 --output 選擇格式，或在 profile 的 output 設定中儲存預設格式：

table（預設）：先輸出一行訊息（如果有），再以縮排 JSON 輸出結果資料。
json：以縮排 JSON 輸出完整結果物件。
ndjson：把完整結果物件輸出在一行裡，方便寫入記錄檔或交給逐行處理的工具。

結果欄位

ok：指令成功時為 true。
code：穩定的結果代碼，例如 common.success 或 cli.argument_missing。
message：簡短的說明文字（如果有）。
data：指令結果，或錯誤的詳細資訊。
meta：呼叫 API 的指令會帶上 HTTP status 和 requestId。

{  "ok": true,  "code": "common.success",  "message": "Workflow spec is valid",  "data": { "valid": true },  "meta": { "status": 200, "requestId": "<request-id>" }}

結束代碼

0：指令執行完畢。
1：沒有更具體代碼的錯誤，包括 401、403、404 以外的 API 錯誤。
2：用法問題，例如缺少參數、JSON 無效、指令未知或時長格式無效。
3：驗證問題，例如未登入、瀏覽器登入被拒絕或過期、缺少 Agent Key，或 API 回傳 401。
4：沒有權限（API 回傳 403）。
5：找不到資源（API 回傳 404）。
6：網路或伺服器問題，例如逾時、連線失敗、上傳失敗，或伺服器不支援所請求的功能。
7：runs wait，或 run 在等待期間，執行結束前就已逾時。
8：profile 沒有設定 API 位址。

範例：在 CI 中驗證規格

#!/usr/bin/env bashset -euo pipefailresult=$(figena spec validate ./workflow.json --output json)if [ "$(echo "$result" | jq -r .ok)" != "true" ]; then  echo "$result" | jq .data  exit 1fiecho "Spec is valid"

重試和逾時

每個請求預設 8 秒逾時，個別指令會設定自己的時限。等待執行結果的指令使用 --timeout。
讀取類請求最多重試兩次。其他請求只有在可以安全重複時才重試一次；執行 OpenPort 操作時從不重試。
遇到 429、502、503、504 回應、逾時或網路錯誤時會重試。CLI 會依伺服器要求的時間等待，最長 5 秒；否則從半秒開始逐步延長等待。

輸出格式

用 --output 選擇格式，或在 profile 的 output 設定中儲存預設格式：

table（預設）：先輸出一行訊息（如果有），再以縮排 JSON 輸出結果資料。

json：以縮排 JSON 輸出完整結果物件。

ndjson：把完整結果物件輸出在一行裡，方便寫入記錄檔或交給逐行處理的工具。

結果欄位

ok：指令成功時為 true。

code：穩定的結果代碼，例如 common.success 或 cli.argument_missing。

message：簡短的說明文字（如果有）。

data：指令結果，或錯誤的詳細資訊。

meta：呼叫 API 的指令會帶上 HTTP status 和 requestId。

{  "ok": true,  "code": "common.success",  "message": "Workflow spec is valid",  "data": { "valid": true },  "meta": { "status": 200, "requestId": "<request-id>" }}

結束代碼

0：指令執行完畢。

1：沒有更具體代碼的錯誤，包括 401、403、404 以外的 API 錯誤。

2：用法問題，例如缺少參數、JSON 無效、指令未知或時長格式無效。

3：驗證問題，例如未登入、瀏覽器登入被拒絕或過期、缺少 Agent Key，或 API 回傳 401。

4：沒有權限（API 回傳 403）。

5：找不到資源（API 回傳 404）。

6：網路或伺服器問題，例如逾時、連線失敗、上傳失敗，或伺服器不支援所請求的功能。

7：runs wait，或 run 在等待期間，執行結束前就已逾時。

8：profile 沒有設定 API 位址。

#!/usr/bin/env bashset -euo pipefailresult=$(figena spec validate ./workflow.json --output json)if [ "$(echo "$result" | jq -r .ok)" != "true" ]; then echo "$result" | jq .data exit 1fiecho "Spec is valid"

重試和逾時

每個請求預設 8 秒逾時，個別指令會設定自己的時限。等待執行結果的指令使用 --timeout。

讀取類請求最多重試兩次。其他請求只有在可以安全重複時才重試一次；執行 OpenPort 操作時從不重試。

遇到 429、502、503、504 回應、逾時或網路錯誤時會重試。CLI 會依伺服器要求的時間等待，最長 5 秒；否則從半秒開始逐步延長等待。