Ligantic
Knowledge Base
Tutorials
Updates
Search Articles
Login
Free Sign Up
Home
Get Started
Tutorials
How-to guides
Reference
Explanation
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Browse documentation
Home
Get Started
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Docs
/

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.

Related pages

Authentication and Key Storage
This explains how the SDK and CLI authenticate, where the CLI keeps your API key, and how the CLI decides which Space, key, and base URL to use.
Page not found. It may have moved or may not be published.
Browse documentation