@optima-chat/bi-cli 0.3.5 → 0.3.6

package/README.md

@@ -1,6 +1,13 @@
 # @optima-chat/bi-cli
 
-Optima BI CLI - AI-friendly business intelligence tool for e-commerce analytics.
+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
 
@@ -8,9 +15,26 @@ Optima BI CLI - AI-friendly business intelligence tool for e-commerce analytics.
 npm install -g @optima-chat/bi-cli
 ```
 
-## Authentication
+## Quick Start
+
+```bash
+# 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
 
-bi-cli uses unified authentication via `~/.optima/token.json`, shared with `commerce-cli` and `optima-agent`.
+# Revenue trends
+bi-cli trends revenue --days 30
+
+# Compare with previous period
+bi-cli analytics compare --days 7
+```
+
+## Authentication
 
 ### Login
 
@@ -28,14 +52,9 @@ bi-cli auth login --env development
 ### Check Status
 
 ```bash
-# Show current user
-bi-cli auth whoami
-
-# Show authentication status
-bi-cli auth status
-
-# Logout
-bi-cli auth logout
+bi-cli auth whoami    # Show current user
+bi-cli auth status    # Show authentication status
+bi-cli auth logout    # Logout
 ```
 
 ### Environment Configuration
@@ -52,93 +71,158 @@ bi-cli auth logout
 2. `OPTIMA_TOKEN` environment variable
 3. `~/.optima/token.json` file
 
-### Environment Variables
-
-```bash
-# 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"
-```
-
 ## Commands
 
 ### Sales Analytics
 
 ```bash
-# Get sales data
-bi-cli sales get
-bi-cli sales get --days 30
+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:
+
+```json
+{
+  "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
 
 ```bash
 # Best selling products
-bi-cli product best-sellers
-bi-cli product best-sellers --limit 10
+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
+# ABC inventory analysis (Pareto)
 bi-cli product abc-analysis
 
-# Price point analysis
+# Price range analysis
 bi-cli product price-analysis
 
-# Product performance
-bi-cli product performance
+# Product performance metrics
+bi-cli product performance --days 30 --limit 20
 ```
 
 ### Trend Analytics
 
 ```bash
-# Revenue trends
-bi-cli trends revenue
-bi-cli trends revenue --days 30
+# 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
+# Orders heatmap by day and hour
 bi-cli trends heatmap
 
-# Seasonal patterns
+# Monthly/seasonal patterns
 bi-cli trends seasonality
 
 # Revenue forecast
-bi-cli trends forecast
+bi-cli trends forecast              # Next 7 days
+bi-cli trends forecast --days 14    # Next 14 days
 ```
 
 ### Advanced Analytics
 
 ```bash
-# Compare periods
-bi-cli analytics compare
-bi-cli analytics compare --days 30
+# 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
+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
+# Customer cohort analysis (LTV)
 bi-cli analytics cohort
 
-# Order funnel analysis
-bi-cli analytics funnel
+# Order status funnel
+bi-cli analytics funnel --days 30
+```
+
+### Traffic Analytics
+
+```bash
+# 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
 ```
 
-## JSON Output
+## Output Formats
 
-All commands output JSON by default, making it easy to integrate with AI agents and other tools.
+### JSON (Default)
+
+All commands output JSON by default, ideal for LLM agents and programmatic use:
 
 ```bash
-# Pipe to jq for formatting
 bi-cli sales get | jq .
-
-# Use with AI agents
 bi-cli product best-sellers --limit 5 | your-ai-tool
 ```
 
+### Pretty Tables
+
+Use `--pretty` flag for human-readable output:
+
+```bash
+bi-cli sales get --pretty
+bi-cli product best-sellers --pretty
+```
+
+## Environment Variables
+
+```bash
+# 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
+
+```bash
+bi-cli sales get --help
+bi-cli product abc-analysis --help
+bi-cli analytics cohort --help
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/bi-cli",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "type": "module",
   "description": "Optima BI CLI - AI-friendly business intelligence tool",
   "main": "dist/index.js",