@opstrails/cli

CLI for OpsTrails event ingestion.

Track deployments, rollbacks, releases, and other infrastructure events from your terminal or CI/CD pipeline.

Installation

npm install -g @opstrails/cli

Or run directly with npx:

npx @opstrails/cli track --type deployment --source "//github.com/org/repo"

Configuration

Set your API key as an environment variable:

export OPSTRAILS_API_KEY=ot_your_api_key

Get your API key from the OpsTrails Console.

Optionally override the API URL:

export OPSTRAILS_API_URL=https://api-staging.opstrails.dev

Commands

opstrails track

Track an infrastructure event.

opstrails track \
  --type deployment \
  --source "//github.com/org/repo" \
  --subject production \
  --version v1.2.3 \
  --severity LOW \
  --description "Deployed v1.2.3"

Options

| Flag | Required | Description | |------|----------|-------------| | -t, --type <type> | Yes | Event type (e.g. deployment, rollback, release) | | -s, --source <source> | Yes | Event source URI (e.g. //github.com/org/repo) | | --subject <subject> | No | Event subject (e.g. environment name) | | --version <version> | No | Version string (e.g. v1.2.3) | | --severity <severity> | No | LOW, MINOR, MAJOR, or CRITICAL | | --description <desc> | No | Event description | | --id <id> | No | Custom event ID | | --time <time> | No | Event time (ISO 8601 or NOW) | | --data <json> | No | Additional data as JSON string | | --json | No | Output as JSON (machine-readable) |

opstrails whoami

Show current API key info.

opstrails whoami
# ✓ API key configured
#   Key:   ot_abc...xyz
#   Scope: READ_WRITE
#   URL:   https://api.opstrails.dev

CI/CD Usage

GitHub Actions

- name: Track deployment
  run: npx @opstrails/cli track --type deployment --source "//github.com/$GITHUB_REPOSITORY" --version "$GITHUB_SHA"
  env:
    OPSTRAILS_API_KEY: ${{ secrets.OPSTRAILS_API_KEY }}

Generic CI

npx @opstrails/cli track \
  --type deployment \
  --source "//github.com/org/repo" \
  --version "$BUILD_VERSION" \
  --subject production \
  --severity LOW \
  --description "Deployed by CI" \
  --json

Exit code is 0 on success, 1 on failure.

Error Handling

| Error | Cause | |-------|-------| | OPSTRAILS_API_KEY environment variable is required | API key not set | | Invalid severity | Severity not one of LOW, MINOR, MAJOR, CRITICAL | | Invalid JSON in --data flag | --data value is not valid JSON | | UNAUTHORIZED | Invalid API key | | FORBIDDEN | API key lacks write permission (read-only otr_ key) | | VALIDATION_ERROR | Request payload validation failed | | QUOTA_EXCEEDED | Monthly event quota reached |

Programmatic Usage

For programmatic access, use the @opstrails/sdk package:

import { OpsTrailsClient } from '@opstrails/sdk'

const client = new OpsTrailsClient({ apiKey: 'ot_your_api_key' })
await client.trackEvent({ type: 'deployment', source: '//github.com/org/repo' })

License

MIT