Installation

npm install -g @stdiolabs/provenance-cli

Quick Start

# 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":"[email protected]"}'

# 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 | — |

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.

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

The track command outputs the generated spanId on success. Use it with --parent-span to build interaction hierarchies:

PARENT=$(provenance track -r order-789 -t ORDER -a CREATE -u $UOWID -d '{"total":99.99}')
provenance track -r payment-456 -t PAYMENT -a PROCESS -u $UOWID \
  --parent-span $PARENT -d '{"method":"card"}'

| 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 | | --parent-span <id> | Link this interaction to a parent span ID | | --span-id <id> | Provide your own span ID (advanced — auto-generated if omitted) | | --stdin | Read data from stdin | | --queue | Push via managed queue |

search

Search and filter interactions.

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.

provenance trace user-123
provenance trace user-123 --json
provenance trace user-123 --tree     # display as span hierarchy tree
provenance trace user-123 --spans    # include spanId/parentSpanId in output

resources

List configured resource types, actions, and origins.

provenance resources actions
provenance resources types
provenance resources origins

alerts

View metric and subscriber alerts.

provenance alerts list
provenance alerts list --firing
provenance alerts subscribers

queue

Monitor and process the notification queue.

provenance queue stats
provenance queue process
provenance queue process --batch 50

secrets

Manage secrets and provider connections.

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.

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.

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.

# 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 under the hood.

CI/CD Integration

GitHub Actions

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

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

License

MIT — STDIO Labs