How to Use the CLI in a Script

This guide shows you how to drive ligantic from a non-interactive script or CI job: provide the API key without a prompt, select a Space, and consume JSON output.

Provide the API Key

Set the key as an environment variable. There is no flag for it:

export LIGANTIC_API_KEY="..."

The CLI resolves the key in this order:

1. LIGANTIC_API_KEY environment variable.
2. The OS key store (set by ligantic auth login).
3. The ~/.ligantic/config.json file — only used as a fallback when no key store is available.

In CI you almost always want option 1.

Select a Space

Resource commands operate on a Space. Set it for the whole script with the environment variable, or per command with --space:

export LIGANTIC_SPACE_ID="..."
ligantic schemas list

or:

ligantic schemas list --space <spaceId>

Precedence is --space flag > LIGANTIC_SPACE_ID env > the active profile's remembered Space from space use/space select, as listed under CLI Command Reference — Config Resolution.

Get JSON Output

When stdout is not a terminal — a pipe, a file, or a CI log — every command prints JSON, so --json is optional in scripts. Passing it anyway keeps the command explicit and makes it behave the same when you run it by hand in a terminal. Errors go to stderr, so you can pipe stdout safely:

ligantic records list customer --limit 10 --json | jq '.records[].id'

To get the human-readable table in a pipe (for example into less), pass --table. The JSON output format is described in CLI Command Reference — Output and Errors.

Handle Failures

In JSON mode a failure is a single-line JSON document on stderr, and the exit code tells you what kind of failure it was:

status=0
out=$(ligantic records show customer "$id" 2>err.json) || status=$?
case $status in
  0) echo "$out" | jq '.data' ;;
  3) echo "check LIGANTIC_API_KEY" ;;
  4) echo "Record $id not found" ;;
  *) jq -r '.error.message' err.json ;;
esac

The exit codes are 0 success, 1 failure, 2 usage error, 3 not authenticated, and 4 not found. See CLI Command Reference — Exit Codes.

A Minimal CI Job

set -euo pipefail

export LIGANTIC_API_KEY="${LIGANTIC_API_KEY:?set LIGANTIC_API_KEY}"
export LIGANTIC_SPACE_ID="${LIGANTIC_SPACE_ID:?set LIGANTIC_SPACE_ID}"

# Verify auth.
ligantic auth whoami --json

# Create a Record and capture its ID.
record_id=$(ligantic records create customer \
  --data '{"name":"Ada"}' --json | jq -r '.entityId')

# Run a Flow and wait for it.
ligantic flows run "${LIGANTIC_FLOW_ID}" \
  --input "{\"orderId\":\"${record_id}\"}" --wait --json

Non-Interactive Caveats

• ligantic auth login is interactive (piped stdin or a hidden prompt). In CI you don't log in — you set LIGANTIC_API_KEY directly.
• ligantic space select is an interactive picker. In CI, set LIGANTIC_SPACE_ID or use --space instead.
• If a command needs a Space and none is resolved, it exits with code 2 and a hint on stderr.