Skip to Content
DocsIntegrationsCLI Quickstart

CLI Quickstart

Status: Active Version: v1.1.0 Last updated: 2026-02-25

Package: @rgl8r/integration-cli v0.1.0 (packages/integration-cli/)

Companion docs:

Installation

The CLI is not yet published to npm. Install from source:

# From the repository root
cd packages/integration-cli
pnpm install
pnpm build
 
# Link globally
npm link

Verify installation:

rgl8r --version
# 0.1.0

Configuration

Set API credentials

# Configure the default profile
rgl8r config set apiKey rgl8r_your_integration_key_here
rgl8r config set apiUrl https://api.rgl8r.com

Multiple profiles

# Create a staging profile
rgl8r config set apiKey rgl8r_staging_key --profile staging
rgl8r config set apiUrl https://staging-api.rgl8r.com --profile staging
 
# Use a specific profile
rgl8r ship upload invoices.csv --profile staging

Environment variables

Environment variables override profile config (highest precedence):

VariablePurpose
RGL8R_API_KEYIntegration key
RGL8R_API_URLAPI base URL
RGL8R_PROFILEProfile name (default: default)

List profiles

rgl8r config list

Configuration is stored at ~/.rgl8r/config.json with 0600 permissions.

Workflows

Ship upload (freight audit)

Upload a shipment CSV for freight audit processing:

rgl8r ship upload invoices.csv

The CLI handles token exchange automatically using your configured integration key.

Dry-run mode

Validate and sanitize a file without uploading:

rgl8r ship upload invoices.csv --dry-run

This runs PII detection and column mapping but does not send data to the API. Use --keep-sanitized to inspect the sanitized output:

rgl8r ship upload invoices.csv --dry-run --keep-sanitized

Strict mode

Reject the entire upload if any PII is detected:

rgl8r ship upload invoices.csv --strict

Exit code 11 if PII patterns are found. Without --strict, PII-containing cells are redacted and the upload proceeds.

Partial uploads

Allow the upload to proceed with valid rows, dropping rejected rows:

rgl8r ship upload invoices.csv --allow-partial

Exit code 2 if rows were dropped (upload succeeded with warnings).

JSON output

Machine-readable output for automation:

rgl8r ship upload invoices.csv --json

Check job status

rgl8r jobs status <jobId>
rgl8r jobs status <jobId> --json

List recent jobs

rgl8r jobs list
rgl8r jobs list --limit 20 --json

SHIP summary

rgl8r ship summary
rgl8r ship summary --json

Upload manifests (local audit trail)

# List recent upload manifests
rgl8r manifests list
 
# Show manifest details
rgl8r manifests show <manifestId>

Manifests are stored locally and include: source file hash, sanitized file hash, row counts, PII redaction counts, and upload outcome.

Exit Codes

CodeConstantMeaning
0SUCCESSUpload or dry run completed successfully
2PARTIALUpload succeeded but some rows were dropped (warnings)
10PREFLIGHT_FAILEDFile not found or adapter unknown
11STRICT_REJECTED--strict set and PII patterns detected
12SANITIZATION_FAILEDRows rejected during sanitization, --allow-partial not set
20AUTH_FAILEDMissing or invalid API key
30UPLOAD_FAILEDNon-auth API error or job failed
50INTERNAL_ERRORUnexpected error

Use exit codes in shell scripts for conditional logic:

rgl8r ship upload invoices.csv --json
case $? in
  0)  echo "Upload succeeded" ;;
  2)  echo "Upload succeeded with warnings — check dropped rows" ;;
  11) echo "PII detected — review file before uploading" ;;
  20) echo "Auth failed — check API key" ;;
  *)  echo "Upload failed (exit code: $?)" ;;
esac

CI/CD Integration

GitHub Actions

- name: Upload shipment data
  env:
    RGL8R_API_KEY: ${{ secrets.RGL8R_API_KEY }}
    RGL8R_API_URL: ${{ vars.RGL8R_API_URL }}
  run: |
    rgl8r ship upload data/shipments.csv --strict --json

Pipeline pattern (upload + poll + verify)

#!/usr/bin/env bash
# Requires: jq (https://jqlang.github.io/jq/)
set -euo pipefail
 
# Upload and capture job ID
OUTPUT=$(rgl8r ship upload data/shipments.csv --json)
JOB_ID=$(echo "$OUTPUT" | jq -r '.jobId')
 
if [ -z "$JOB_ID" ] || [ "$JOB_ID" = "null" ]; then
  echo "Upload failed — no job ID returned"
  exit 1
fi
 
echo "Job started: $JOB_ID"
 
# Poll until complete
for i in $(seq 1 40); do
  STATUS=$(rgl8r jobs status "$JOB_ID" --json | jq -r '.status')
  if [ "$STATUS" = "COMPLETED" ]; then
    echo "Job completed successfully"
    rgl8r ship summary --json
    exit 0
  elif [ "$STATUS" = "FAILED" ]; then
    echo "Job failed"
    rgl8r jobs status "$JOB_ID" --json
    exit 1
  fi
  sleep 5
done
 
echo "Job timed out after 40 polls"
exit 1

Troubleshooting

SymptomLikely CauseAction
rgl8r: command not foundCLI not linked or not in PATHRun npm link from packages/integration-cli/
Exit code 20 (AUTH_FAILED)Bad or missing API keyRun rgl8r config set apiKey <key> or set RGL8R_API_KEY env var
Exit code 10 (PREFLIGHT_FAILED)File not found or unknown adapterCheck file path; omit --adapter to use tenant default
Exit code 11 (STRICT_REJECTED)PII detected in strict modeRun --dry-run --keep-sanitized to inspect; fix source data or remove --strict
Exit code 12 (SANITIZATION_FAILED)Rows rejected, --allow-partial not setAdd --allow-partial to drop bad rows, or fix source data
Exit code 30 (UPLOAD_FAILED)API error or job failureCheck rgl8r jobs status <id> --json for error details
--json output emptyCLI version mismatchRebuild: cd packages/integration-cli && pnpm build

Next Steps

  • npm publishing: @rgl8r/integration-cli will be published to npm (install via npm install -g @rgl8r/integration-cli)
  • Catalog upload: rgl8r catalog upload command (TRADE catalog ingestion)
  • Webhook mode (P12-B): rgl8r ship upload --webhook <url> to receive completion callbacks instead of polling

Plan ID: P12-A | Last updated: 2026-02-25

Integration Quickstartsn8n Quickstart