npm package: @stdiolabs/provenance-cli
Description: CLI for the Provenance platform — track interactions, search data, view traces, monitor alerts, and manage configuration
Author: STDIO Labs
Latest version: 1.0.1

<p align="center">
  <img src="https://www.stdiolabs.dev/images/stdio-logo-white-font.png" alt="STDIO Labs" height="32" />
</p>

<h1 align="center">Provenance CLI</h1>

<p align="center">
  Command-line interface for the <a href="https://provenance.dev">Provenance</a> platform — record interactions, search data, view traces, monitor alerts, and manage configuration from your terminal.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@stdiolabs/provenance-cli"><img src="https://img.shields.io/npm/v/@stdiolabs/provenance-cli" alt="npm version" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version" /></a>
</p>

---

## Installation

```bash
npm install -g @stdiolabs/provenance-cli
```

## Quick Start

```bash
# Configure
provenance config set apiUrl https://your-api.provenance.dev/api
provenance config set apiKey your-api-key
provenance config set origin MY-SERVICE

# Track an interaction
provenance track -r user-123 -t USER -a CREATE -d '{"email":"user@example.com"}'

# Search
provenance search -r user-123

# View trace
provenance trace user-123
```

## Configuration

Configuration is stored persistently. Environment variables take priority — ideal for CI/CD.

| Key | Environment Variable | Default |
|-----|---------------------|---------|
| `apiUrl` | `PROVENANCE_API_URL` | `http://localhost:4000/api` |
| `apiKey` | `PROVENANCE_API_KEY` | — |
| `origin` | `PROVENANCE_ORIGIN` | — |
| `outputFormat` | — | `table` |
| `useQueue` | `PROVENANCE_USE_QUEUE` | `false` |
| `platformUrl` | `PROVENANCE_PLATFORM_URL` | — |

```bash
provenance config set apiUrl https://your-api.provenance.dev/api
provenance config list
provenance config path
provenance config reset
```

## Commands

### track

Record a provenance interaction. Accepts mnemonics or UUIDs.

```bash
provenance track -r order-456 -t ORDER -a CREATE -d '{"total":99.99}'
provenance track -r order-456 -t ORDER -a UPDATE --user admin-1 -u 550e8400-...
echo '{"status":"complete"}' | provenance track -r job-1 -t JOB -a EXECUTE --stdin
provenance track -r order-456 -t ORDER -a CREATE --queue  # via managed queue
```

| Option | Description |
|--------|-------------|
| `-r, --resource <id>` | Resource ID (required) |
| `-t, --type <id>` | Resource Type mnemonic or UUID (required) |
| `-a, --action <id>` | Action mnemonic or UUID (required) |
| `-o, --origin <id>` | Origin (falls back to config) |
| `-u, --uow <id>` | Unit of Work ID |
| `--user <id>` | User ID |
| `-d, --data <json>` | Interaction data as JSON |
| `--stdin` | Read data from stdin |
| `--queue` | Push via managed queue |

### search

Search and filter interactions.

```bash
provenance search --last 7d
provenance search -r user-123 -a CREATE --last 24h
provenance search --uow 550e8400-... --json
```

| Option | Description |
|--------|-------------|
| `-r, --resource <id>` | Filter by resource ID |
| `-a, --action <mnemonic>` | Filter by action |
| `-t, --type <mnemonic>` | Filter by resource type |
| `-o, --origin <mnemonic>` | Filter by origin |
| `--user <id>` | Filter by user ID |
| `--uow <id>` | Filter by Unit of Work ID |
| `--last <duration>` | Time range: `5m`, `1h`, `24h`, `7d`, `30d` |
| `--limit <n>` | Max results (default: 25) |
| `--json` | Output as JSON |

### trace

View the interaction trace for a resource.

```bash
provenance trace user-123
provenance trace user-123 --json
```

### resources

List configured resource types, actions, and origins.

```bash
provenance resources actions
provenance resources types
provenance resources origins
```

### alerts

View metric and subscriber alerts.

```bash
provenance alerts list
provenance alerts list --firing
provenance alerts subscribers
```

### queue

Monitor and process the notification queue.

```bash
provenance queue stats
provenance queue process
provenance queue process --batch 50
```

### secrets

Manage secrets and provider connections.

```bash
provenance secrets list
provenance secrets create -p sendgrid.apiKey --provider provenance -v "SG.key"
provenance secrets test sendgrid.apiKey
provenance secrets providers list
provenance secrets providers types
```

### uow

Generate Unit of Work IDs.

```bash
provenance uow new
UOWID=$(provenance uow new)
provenance track -r res-1 -t TYPE -a CREATE -u $UOWID
provenance track -r res-2 -t TYPE -a UPDATE -u $UOWID
```

### config

Manage persistent configuration.

```bash
provenance config set <key> <value>
provenance config get <key>
provenance config list
provenance config path
provenance config reset
```

## Queue Mode

Push interactions through a managed queue for reliable async delivery with automatic retries.

```bash
# One-off
provenance track -r order-456 -t ORDER -a CREATE --queue

# Enable globally
provenance config set useQueue true
```

Requires a provisioned queue and an active API key. Uses the [Provenance SDK](https://www.npmjs.com/package/provenance-sdk) under the hood.

## CI/CD Integration

### GitHub Actions

```yaml
- name: Record Deployment
  env:
    PROVENANCE_API_URL: ${{ secrets.PROVENANCE_API_URL }}
    PROVENANCE_API_KEY: ${{ secrets.PROVENANCE_API_KEY }}
    PROVENANCE_ORIGIN: GITHUB_ACTIONS
  run: |
    npx @stdiolabs/provenance-cli track \
      -r ${{ github.repository }} \
      -t DEPLOYMENT -a CREATE \
      -d '{"sha":"${{ github.sha }}","branch":"${{ github.ref_name }}"}'
```

## Output Formats

**Table** (default) — human-readable, ideal for interactive use.

**JSON** — machine-readable, for scripting and piping.

```bash
provenance search --last 7d --json
provenance config set outputFormat json  # set globally
```

## License

MIT — [STDIO Labs](https://www.stdiolabs.dev)