在脚本中使用 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 秒；否则从半秒开始逐步延长等待。