@reaatech/llm-cost-telemetry-cli

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

CLI tool for LLM cost telemetry operations — generate cost reports, check budget status, and trigger exports to observability platforms. Reads cost spans from JSON files or stdin.

Installation

npm install -g @reaatech/llm-cost-telemetry-cli
# or
pnpm add -g @reaatech/llm-cost-telemetry-cli

Feature Overview

• Cost reports — aggregate cost spans and output as JSON or human-readable tables
• Budget checks — verify tenant budget status with configurable thresholds
• Export triggering — push cost data to CloudWatch, Cloud Monitoring, or Phoenix/Loki
• Pipe-friendly — reads spans from stdin for shell pipeline integration
• JSON input — accepts arrays of cost span objects from files or pipes

Commands

report — Generate Cost Reports

llm-cost-telemetry report --tenant acme-corp --period day
llm-cost-telemetry report --feature chat-support --period month --format table
llm-cost-telemetry report --input spans.json --format json

Aggregates cost spans and displays a cost summary grouped by configurable dimensions.

Options:

Example output (table format):

┌──────────────┬──────────┬───────────┬────────────┐
│ Tenant       │ Feature  │ Provider  │ Cost (USD) │
├──────────────┼──────────┼───────────┼────────────┤
│ acme-corp    │ support  │ openai    │ $42.50     │
│ acme-corp    │ support  │ anthropic │ $12.30     │
│ startup-inc  │ onboard  │ openai    │ $8.20      │
├──────────────┼──────────┼───────────┼────────────┤
│ Total        │          │           │ $63.00     │
└──────────────┴──────────┴───────────┴────────────┘

check — Check Budget Status

llm-cost-telemetry check --tenant acme-corp
llm-cost-telemetry check --tenant startup-inc --threshold 0.8

Verifies budget status for a tenant against configured limits.

Options:

Example output:

Tenant: acme-corp
  Daily:   $42.50 / $100.00 (42.5%)  OK
  Monthly: $142.30 / $2000.00 (7.1%) OK

export — Trigger Export

llm-cost-telemetry export --exporter cloudwatch --period hour
llm-cost-telemetry export --exporter phoenix --input spans.json
llm-cost-telemetry export --exporter cloudwatch --dry-run

Builds aggregated cost records and pushes them to the specified exporter.

Options:

config — Show Configuration

llm-cost-telemetry config

Displays the effective configuration loaded from environment variables.

version — Show Version

llm-cost-telemetry version

Prints the CLI version number.

Usage Patterns

Pipe Spans from stdin

curl -s https://api.example.com/cost-spans | llm-cost-telemetry report

Scripted Budget Checks

#!/bin/bash
status=$(llm-cost-telemetry check --tenant acme-corp --format json)
percentage=$(echo "$status" | jq -r '.dailyPercentage')
 
if (( $(echo "$percentage > 80" | bc -l) )); then
  echo "WARNING: acme-corp at ${percentage}% of daily budget"
  exit 1
fi

Export to Multiple Targets

llm-cost-telemetry export --exporter cloudwatch --input spans.json
llm-cost-telemetry export --exporter phoenix --input spans.json

Batch Processing with Dry Run

# Preview what would be exported without actually sending
llm-cost-telemetry export --exporter cloudwatch --dry-run

Environment Variables

The CLI reads configuration from the same environment variables as @reaatech/llm-cost-telemetry:

Related Packages

• @reaatech/llm-cost-telemetry — Core types and configuration
• @reaatech/llm-cost-telemetry-aggregation — Aggregation and budgets
• @reaatech/llm-cost-telemetry-exporters — CloudWatch, Cloud Monitoring, Phoenix

License

MIT