npm package: @opstrails/cli
Description: CLI for OpsTrails event ingestion
Latest version: 0.1.0

# @opstrails/cli

CLI for [OpsTrails](https://opstrails.dev) event ingestion.

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

## Installation

```bash
npm install -g @opstrails/cli
```

Or run directly with npx:

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

## Configuration

Set your API key as an environment variable:

```bash
export OPSTRAILS_API_KEY=ot_your_api_key
```

Get your API key from the [OpsTrails Console](https://console.opstrails.dev).

Optionally override the API URL:

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

## Commands

### `opstrails track`

Track an infrastructure event.

```bash
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.

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

## CI/CD Usage

### GitHub Actions

```yaml
- 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

```bash
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](https://www.npmjs.com/package/@opstrails/sdk) package:

```typescript
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](LICENSE)