@optima-chat/bi-cli

Optima BI CLI - E-commerce business intelligence tool designed for LLM agents.

Features

• LLM-Friendly: Detailed help messages with JSON schemas and examples
• JSON Output: All commands output JSON by default for programmatic parsing
• Pretty Tables: Use --pretty flag for human-readable table format
• Unified Auth: Shared authentication with commerce-cli and optima-agent

Installation

npm install -g @optima-chat/bi-cli

Quick Start

# Login first (required)
bi-cli auth login

# Get sales data
bi-cli sales get --days 7

# Top selling products
bi-cli product best-sellers --limit 10

# Revenue trends
bi-cli trends revenue --days 30

# Compare with previous period
bi-cli analytics compare --days 7

Authentication

Login

# Login to production (default)
bi-cli auth login

# Login to stage environment
bi-cli auth login --env stage

# Login to development environment
bi-cli auth login --env development

Check Status

bi-cli auth whoami    # Show current user
bi-cli auth status    # Show authentication status
bi-cli auth logout    # Logout

Environment Configuration

| Environment | Auth URL | Backend URL | | ----------- | --------------------- | ----------------------- | | production | auth.optima.onl | bi-api.optima.onl | | stage | auth.stage.optima.onl | bi-api.stage.optima.onl | | development | auth.optima.chat | bi-api.optima.chat |

Token Priority

1. BI_CLI_TOKEN environment variable
2. OPTIMA_TOKEN environment variable
3. ~/.optima/token.json file

Commands

Sales Analytics

bi-cli sales get                     # Get last 7 days (default)
bi-cli sales get --days 30           # Get last 30 days
bi-cli sales get --days 7 --pretty   # Output as table

Returns:

{
  "summary": {
    "total_revenue": 10000,
    "total_orders": 100,
    "avg_order_value": 100,
    "unique_customers": 80
  },
  "daily": [{ "date": "2024-01-01", "total_revenue": 1500, "order_count": 15 }]
}

Product Analytics

# Best selling products
bi-cli product best-sellers                      # Top 10 by revenue
bi-cli product best-sellers --limit 5            # Top 5
bi-cli product best-sellers --sort quantity      # Sort by quantity

# ABC inventory analysis (Pareto)
bi-cli product abc-analysis

# Price range analysis
bi-cli product price-analysis

# Product performance metrics
bi-cli product performance --days 30 --limit 20

Trend Analytics

# Revenue trends with moving average
bi-cli trends revenue                        # Last 30 days, daily
bi-cli trends revenue --granularity hourly   # Hourly granularity
bi-cli trends revenue --granularity weekly   # Weekly granularity

# Orders heatmap by day and hour
bi-cli trends heatmap

# Monthly/seasonal patterns
bi-cli trends seasonality

# Revenue forecast
bi-cli trends forecast              # Next 7 days
bi-cli trends forecast --days 14    # Next 14 days

Advanced Analytics

# Period comparison
bi-cli analytics compare                              # Last 30 days vs previous
bi-cli analytics compare --days 7                     # This week vs last week
bi-cli analytics compare --compare-to previous_year   # Year-over-year

# Growth trends
bi-cli analytics growth                         # Daily, last 30 periods
bi-cli analytics growth --period weekly         # Weekly
bi-cli analytics growth --period monthly        # Monthly

# Customer cohort analysis (LTV)
bi-cli analytics cohort

# Order status funnel
bi-cli analytics funnel --days 30

Traffic Analytics

# Traffic overview
bi-cli traffic overview                     # Last 30 days
bi-cli traffic overview --days 7            # Last 7 days
bi-cli traffic overview --product <uuid>    # Filter by product

# Traffic sources
bi-cli traffic sources --limit 10

# Conversion funnel
bi-cli traffic funnel

# Site search analytics
bi-cli traffic search
bi-cli traffic search --zero-results        # Zero-result queries only

# Top pages
bi-cli traffic pages --limit 20

Output Formats

JSON (Default)

All commands output JSON by default, ideal for LLM agents and programmatic use:

bi-cli sales get | jq .
bi-cli product best-sellers --limit 5 | your-ai-tool

Pretty Tables

Use --pretty flag for human-readable output:

bi-cli sales get --pretty
bi-cli product best-sellers --pretty

Environment Variables

# Override token
export BI_CLI_TOKEN="your-access-token"

# Override URLs
export BI_CLI_BACKEND_URL="https://custom-api.example.com"
export BI_CLI_AUTH_URL="https://custom-auth.example.com"

# Override environment
export BI_CLI_ENV="stage"

For LLM Agents

Each command includes detailed help with:

• Function description
• JSON return structure
• Usage examples
• Parameter descriptions with valid values

bi-cli sales get --help
bi-cli product abc-analysis --help
bi-cli analytics cohort --help

License

MIT