The Provenance CLI brings the full API to your terminal — ideal for developers, DevOps, and CI/CD pipelines.

Installation

npm install -g @stdiolabs/provenance-cli

Configuration

provenance config set apiUrl https://provenance.onrender.com/api
provenance config set apiKey your-api-key
provenance config set origin CLI

Or use environment variables:

export PROVENANCE_API_URL=https://provenance.onrender.com/api
export PROVENANCE_API_KEY=your-api-key
export PROVENANCE_ORIGIN=CLI

Commands

track

Record an interaction using mnemonics instead of UUIDs:

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

The track command outputs the generated spanId. Use --parent-span to link child interactions:

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"}'

search

provenance search --last 7d
provenance search -r user-123
provenance search -a CREATE -t USER --last 24h

trace

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

resources

provenance resources actions
provenance resources types
provenance resources origins

alerts

provenance alerts list
provenance alerts list --firing
provenance alerts list --kind alert    # only alerts
provenance alerts list --kind goal     # only goals
provenance alerts create --title "Revenue Target" --metric-id uuid --operator gte \
  --threshold 100000 --alert-action-id uuid --kind goal

Flag	Command	Description
`--kind <alert\|goal>`	`list`	Filter alerts by kind
`--kind <alert\|goal>`	`create`	Set alert kind (default: `"alert"`)

subscriptions

provenance subscriptions list
provenance subscriptions list --label Production
provenance subscriptions create --action-id uuid --resource-type-id uuid \
  --subscriber-id uuid --labels "Production,Billing,high-priority"
provenance subscriptions update <id> --labels "Production,Security"

Flag	Command	Description
`--label <value>`	`list`	Filter subscriptions containing this label
`--labels <comma-separated>`	`create`, `update`	Set subscription labels

queue

provenance queue stats
provenance queue process --batch 50

secrets

Manage secrets and provider connections:

# List all secrets
provenance secrets list

# Create a provenance-stored secret
provenance secrets create -p sendgrid.apiKey --provider provenance -v "SG.actual-key"

# Create an external provider secret
provenance secrets create -p stripe.webhookSecret --provider aws-sm --provider-path prod/stripe/webhook --provider-id <uuid>

# Create an environment variable secret (self-hosted only)
provenance secrets create -p slack.token --provider environment --provider-path SLACK_BOT_TOKEN

# Test a secret (resolve and verify)
provenance secrets test sendgrid.apiKey

# Delete a secret
provenance secrets delete <secretId>

# List provider connections
provenance secrets providers list

# List available provider types
provenance secrets providers types

# Create a provider connection
provenance secrets providers create -n "Production AWS" -t aws-sm -c '{"region":"eu-west-1"}'

# Delete a provider connection
provenance secrets providers delete <providerId>

Queue mode

Push interactions through a managed queue for reliable async delivery:

provenance config set useQueue true
provenance track -r order-456 -t ORDER -a CREATE -d '{"total":99.99}'

CI/CD example

- name: Record Deployment
  env:
    PROVENANCE_API_URL: $\{{ secrets.PROVENANCE_API_URL }}
    PROVENANCE_API_KEY: $\{{ secrets.PROVENANCE_API_KEY }}
    PROVENANCE_ORIGIN: GITHUB_ACTIONS
  run: |
    provenance track \
      -r $\{{ github.repository }} \
      -t DEPLOYMENT \
      -a CREATE \
      -d '{"sha":"$\{{ github.sha }}"}'

CLI

On this page