How to Run a Flow from CI

This guide shows you how to trigger a Flow from a non-interactive job (a CI pipeline, a cron job, a serverless function) and wait for it to finish, using either the SDK or the CLI.

A Flow run is asynchronous: flows.run returns the run's flowExecutionId immediately. To gate a CI step on the Flow's outcome you must poll the run until it reaches a terminal status (succeeded, failed, or cancelled).

With the SDK

import { Ligantic } from "@ligantic/sdk";

const client = new Ligantic({ apiKey: process.env.LIGANTIC_API_KEY! });

const spaceId = process.env.LIGANTIC_SPACE_ID!;
const flowId = process.env.LIGANTIC_FLOW_ID!;

const executed = await client.flows.run(spaceId, flowId, {
  inputs: {
    /* flow input handles */
  },
});
if (!executed.ok) {
  throw new Error(`run failed: ${executed.error.code} ${executed.error.message}`);
}

const runId = executed.value.flowExecutionId;

const terminal = new Set(["succeeded", "failed", "cancelled"]);
let run;
for (;;) {
  const res = await client.flows.getRun(spaceId, flowId, runId);
  if (!res.ok) {
    throw new Error(`getRun failed: ${res.error.code} ${res.error.message}`);
  }
  run = res.value;
  if (terminal.has(run.status)) break;
  await new Promise((r) => setTimeout(r, 1000));
}

if (run.status !== "succeeded") {
  throw new Error(`flow run ${run.status}`);
}

const outputs = await client.flows.getRunOutputs(spaceId, flowId, runId);
if (outputs.ok) {
  console.log("outputs:", outputs.value.outputs);
}

Notes:

• Add a wall-clock timeout around the polling loop so a stuck run can't hang the job forever.
• getRunOutputs returns the run's output handles under outputs (a map of handle name → value, or null if the Flow produced none).
• If you only need to start the Flow and not wait, call run and stop — the run continues after your job exits.

With the CLI

The CLI does the polling for you with --wait, as listed under CLI Command Reference — Flows:

ligantic flows run "$LIGANTIC_FLOW_ID" --wait

--wait polls to completion and prints the final run. Without --wait, flows run prints the run ID and returns immediately.

In a CI environment the key comes from the environment, not a prompt:

export LIGANTIC_API_KEY="..."
export LIGANTIC_SPACE_ID="..."
ligantic flows run "$LIGANTIC_FLOW_ID" --input '{"orderId": 1234}' --wait --json

See How to Use the CLI in a Script for the full non-interactive setup.