Use Figena CLI output in scripts

Choose an output format, read the result fields, handle exit codes, and understand retries and timeouts.

Developer toolsFigena CLI3 min read

Overview

Every Figena CLI command returns the same result shape, so scripts can rely on one structure whether a command succeeds or fails. This article covers output formats, result fields, exit codes, and how the CLI retries requests.

Output formats

Choose a format with --output or save one in the profile’s output setting:

table (default): a message line, if any, followed by the result data as indented JSON.
json: the complete result object as indented JSON.
ndjson: the complete result object on a single line, convenient for logs and line-based tools.

Result fields

ok: true when the command succeeded.
code: a stable result code, such as common.success or cli.argument_missing.
message: a short human-readable summary, when there is one.
data: the command’s result, or details about an error.
meta: for commands that call the API, the HTTP status and the requestId.

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

Exit codes

0: the command finished.
1: an error that has no more specific code, including API errors other than 401, 403, and 404.
2: a usage problem, such as a missing argument, invalid JSON, an unknown command, or an invalid duration.
3: authentication, for example no sign-in, a declined or expired browser sign-in, a missing Agent Key, or an API 401 response.
4: permission denied (API 403).
5: not found (API 404).
6: a network or server problem, such as a timeout, a failed connection, a failed upload, or a server that doesn’t support the requested feature.
7: runs wait, or run while waiting, timed out before the run finished.
8: no API address is configured for the profile.

Example: validate a spec in 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"

Retries and timeouts

Each request times out after 8 seconds unless the command sets its own limit. Commands that wait for a run use --timeout.
Read requests are retried up to two times. Other requests are retried once only when repeating them is safe, and never when an OpenPort action is executed.
Retries happen after a 429, 502, 503, or 504 response, a timeout, or a network error. The CLI waits as long as the server asks, up to 5 seconds, or backs off from half a second.

Output formats

Choose a format with --output or save one in the profile’s output setting:

table (default): a message line, if any, followed by the result data as indented JSON.

json: the complete result object as indented JSON.

ndjson: the complete result object on a single line, convenient for logs and line-based tools.

Result fields

ok: true when the command succeeded.

code: a stable result code, such as common.success or cli.argument_missing.

message: a short human-readable summary, when there is one.

data: the command’s result, or details about an error.

meta: for commands that call the API, the HTTP status and the requestId.

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

Exit codes

0: the command finished.

1: an error that has no more specific code, including API errors other than 401, 403, and 404.

2: a usage problem, such as a missing argument, invalid JSON, an unknown command, or an invalid duration.

3: authentication, for example no sign-in, a declined or expired browser sign-in, a missing Agent Key, or an API 401 response.

4: permission denied (API 403).

5: not found (API 404).

6: a network or server problem, such as a timeout, a failed connection, a failed upload, or a server that doesn’t support the requested feature.

7: runs wait, or run while waiting, timed out before the run finished.

8: no API address is configured for the profile.

#!/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"

Retries and timeouts

Each request times out after 8 seconds unless the command sets its own limit. Commands that wait for a run use --timeout.

Read requests are retried up to two times. Other requests are retried once only when repeating them is safe, and never when an OpenPort action is executed.

Retries happen after a 429, 502, 503, or 504 response, a timeout, or a network error. The CLI waits as long as the server asks, up to 5 seconds, or backs off from half a second.