CLI & CI/CD Integration

Integrate compliance testing into your build pipeline. No dedicated CLI binary required — use curl or the Convex SDK directly from any shell or CI environment.

Prerequisites

›A Lumis workspace on any plan (Free tier works for up to 100 simulations/month)
›An API key generated from Settings → API Keys
›The rulesetId of an active ruleset (visible in the console URL or control bar)
›curl or any standard HTTP client (e.g. fetch, axios)

Store your API key as an environment variable — never hard-code it in source files or commit it to version control.

Running a simulation with curl

bash

# Set your credentials
export LUMIS_API_KEY="lmk_live_••••••••••••••••"
export RULESET_ID="jx7abc123"

# Run a single simulation
curl -s -X POST "https://lumiscompliance.com/api/v1/simulate" \
  -H "Authorization: Bearer $LUMIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"rulesetId\": \"$RULESET_ID\",
    \"payload\": {
      \"transaction_amount\": 2500,
      \"user_region\": \"US\",
      \"id_verified\": true,
      \"risk_score\": 0.15
    }
  }" | jq .status

The command above prints passed or failed — perfect for a CI health check.

GitHub Actions workflow

Add Lumis compliance checks as a required CI step. The example below fails the build if any test payload produces a non-passing result.

.github/workflows/compliance.yml

name: Compliance Checks

on:
  pull_request:
    branches: [main]

jobs:
  lumis-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run KYC simulation
        env:
          LUMIS_API_KEY: ${{ secrets.LUMIS_API_KEY }}
          RULESET_ID: ${{ vars.LUMIS_RULESET_ID }}
        run: |
          # Construct payload with rulesetId
          PAYLOAD=$(jq -n --arg rid "$RULESET_ID" --argjson p "$(cat test-fixtures/kyc-payload.json)" \
            '{rulesetId: $rid, payload: $p}')

          RESULT=$(curl -s -X POST "https://lumiscompliance.com/api/v1/simulate" \
            -H "Authorization: Bearer $LUMIS_API_KEY" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD" | jq -r .data.status)

          echo "Compliance result: $RESULT"
          if [ "$RESULT" != "passed" ]; then
            echo "::error::Compliance simulation failed"
            exit 1
          fi

Store LUMIS_API_KEY as a repository secret and LUMIS_RULESET_ID as a repository variable (not secret, it's not sensitive).

Node.js / TypeScript

compliance-check.ts

async function runComplianceCheck(payload: Record<string, unknown>) {
  const response = await fetch(
    "https://lumiscompliance.com/api/v1/simulate",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.LUMIS_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        rulesetId: process.env.LUMIS_RULESET_ID,
        payload: payload
      })
    }
  );

  const { data: result } = await response.json();

  if (result.status !== "passed") {
    console.error("Compliance check failed at node:", result.failedNodeId);
    process.exit(1);
  }

  console.log("Compliance passed. Steps:", result.stepsExecuted);
}

runComplianceCheck({
  transaction_amount: 2500,
  user_region: "US",
  id_verified: true,
  risk_score: 0.15,
});

Programmatic Batch Simulation

For high-volume testing, use the programmatic batch endpoint. This allows you to evaluate up to 50 payloads in a single request, which is significantly more efficient than individual calls.

bash

curl -s -X POST "https://lumiscompliance.com/api/v1/simulate/batch" \
  -H "Authorization: Bearer $LUMIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rulesetId": "jx7abc123",
    "payloads": [
      { "transaction_amount": 500, "user_region": "US" },
      { "transaction_amount": 9500, "user_region": "GH" }
    ]
  }' | jq .data.transactionIds

Alternatively, you can upload a CSV file from the Dashboard for manual batch processing.

Shell exit codes

Exit code	Meaning
`0`	Simulation passed — all checks cleared
`1`	Simulation failed or API error — pipeline should block