@optima-chat/bi-cli 0.3.4 → 0.3.5

package/src/commands/auth.ts

@@ -38,13 +38,25 @@ interface UserInfo {
 }
 
 export function createAuthCommand(): Command {
-  const auth = new Command('auth').description('Authentication commands');
+  const auth = new Command('auth').description(
+    `Authentication commands.
+
+You must login before using other commands. Tokens are saved to ~/.optima/token.json.`
+  );
 
   // auth login
   auth
     .command('login')
-    .description('Login with OAuth 2.0 Device Flow')
-    .option('--env <environment>', 'Environment (production|stage|development)', 'production')
+    .description(
+      `Login using OAuth 2.0 Device Flow.
+
+Opens browser automatically for authorization. Token is saved after successful auth.
+
+Examples:
+  bi-cli auth login                    # Login to production (default)
+  bi-cli auth login --env stage        # Login to staging environment`
+    )
+    .option('--env <environment>', 'Environment: production | stage | development', 'production')
     .action(async (options) => {
       const env = options.env as Environment;
 
@@ -206,7 +218,7 @@ export function createAuthCommand(): Command {
   // auth logout
   auth
     .command('logout')
-    .description('Logout and delete ~/.optima/token.json')
+    .description('Logout and delete local token file (~/.optima/token.json)')
     .action(() => {
       clearAuth();
       success('Logged out successfully');
@@ -216,7 +228,7 @@ export function createAuthCommand(): Command {
   // auth whoami
   auth
     .command('whoami')
-    .description('Show current user information')
+    .description('Show current user info (email, role, merchant ID)')
     .action(async () => {
       const cfg = getConfig();
 
@@ -260,7 +272,7 @@ export function createAuthCommand(): Command {
   // auth status
   auth
     .command('status')
-    .description('Show authentication status')
+    .description('Show authentication status (environment, login state, config path)')
     .action(() => {
       const cfg = getConfig();
 

package/src/commands/product.ts

@@ -88,15 +88,36 @@ interface PerformanceResponse {
 }
 
 export function createProductCommand(): Command {
-  const product = new Command('product').description('Product analytics');
+  const product = new Command('product').description(
+    `Product analytics.
+
+Analyze product performance, price distribution, ABC classification.`
+  );
 
   // product best-sellers
   product
     .command('best-sellers')
-    .description('Get best selling products')
-    .option('--limit <number>', 'Number of products to return', '10')
-    .option('--sort <field>', 'Sort by: revenue, quantity, orders', 'revenue')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Get best selling products ranking.
+
+Returns products sorted by revenue/quantity/orders with rank, revenue, units sold, revenue share.
+
+Returns JSON:
+{
+  "products": [
+    { "rank": 1, "title": "Product Name", "revenue": 1000, "units_sold": 50, "orders": 30, "revenue_share": 15.5 }
+  ],
+  "total_revenue": number
+}
+
+Examples:
+  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`
+    )
+    .option('--limit <number>', 'Number of products to return (default: 10)', '10')
+    .option('--sort <field>', 'Sort by: revenue | quantity | orders', 'revenue')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -147,8 +168,23 @@ export function createProductCommand(): Command {
   // product abc-analysis
   product
     .command('abc-analysis')
-    .description('ABC inventory analysis')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `ABC inventory analysis (Pareto analysis).
+
+Classifies products by revenue contribution:
+  - A: High-value products contributing 70% of revenue (typically ~20% of products)
+  - B: Medium-value products contributing 20% of revenue
+  - C: Low-value products contributing 10% of revenue
+
+Use case: Identify core products, optimize inventory and purchasing strategy.
+
+Returns JSON:
+{
+  "summary": { "A": {...}, "B": {...}, "C": {...} },
+  "products": [ { "title": "Product Name", "category": "A", "revenue": number, ... } ]
+}`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -205,8 +241,20 @@ export function createProductCommand(): Command {
   // product price-analysis
   product
     .command('price-analysis')
-    .description('Price point analysis')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Price range analysis.
+
+Analyze product count, revenue, and sales by price ranges.
+
+Returns JSON:
+{
+  "price_ranges": [
+    { "range": "¥0-50", "products": 10, "revenue": 5000, "units": 200, "revenue_share": 15.5 }
+  ],
+  "totals": { "revenue": number, "units": number }
+}`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -256,10 +304,36 @@ export function createProductCommand(): Command {
   // product performance
   product
     .command('performance')
-    .description('Get product performance metrics')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Number of products', '20')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Product performance metrics.
+
+Get sales, inventory, and margin metrics for each product.
+
+Returns JSON:
+{
+  "products": [
+    {
+      "title": "Product Name",
+      "price": 99.00,           // Selling price
+      "inventory": 50,          // Current stock
+      "sales": { "units": 100, "revenue": 9900, "orders": 80 },
+      "metrics": {
+        "margin_percent": 30.5, // Profit margin (%)
+        "days_of_stock": 15,    // Estimated days of stock
+        "velocity": 6.7         // Daily sales rate
+      }
+    }
+  ]
+}
+
+Examples:
+  bi-cli product performance                  # Last 30 days, top 20 products
+  bi-cli product performance --days 7         # Last 7 days
+  bi-cli product performance --limit 50       # Top 50 products`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of products (default: 20)', '20')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {

package/src/commands/sales.ts

@@ -33,14 +33,38 @@ interface SalesResponse {
 }
 
 export function createSalesCommand(): Command {
-  const sales = new Command('sales').description('Sales analytics');
+  const sales = new Command('sales').description(
+    `Sales analytics.
+
+Get sales summary and daily breakdown data.`
+  );
 
   // sales get
   sales
     .command('get')
-    .description('Get sales data')
-    .option('--days <number>', 'Number of days to fetch', '7')
-    .option('--pretty', 'Output in pretty table format (default: JSON)')
+    .description(
+      `Get sales summary and daily breakdown.
+
+Returns JSON:
+{
+  "summary": {
+    "total_revenue": number,      // Total revenue (CNY)
+    "total_orders": number,       // Total order count
+    "avg_order_value": number,    // Average order value (CNY)
+    "unique_customers": number    // Unique customer count
+  },
+  "daily": [                      // Daily breakdown array
+    { "date": "YYYY-MM-DD", "total_revenue": number, "order_count": number, ... }
+  ]
+}
+
+Examples:
+  bi-cli sales get                     # Get last 7 days
+  bi-cli sales get --days 30           # Get last 30 days
+  bi-cli sales get --days 7 --pretty   # Output as table`
+    )
+    .option('--days <number>', 'Number of days from today (range: 1-365)', '7')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 

package/src/commands/traffic.ts

@@ -69,15 +69,44 @@ function formatDuration(seconds: number): string {
 }
 
 export function createTrafficCommand(): Command {
-  const traffic = new Command('traffic').description('Traffic analytics');
+  const traffic = new Command('traffic').description(
+    `Traffic analytics.
+
+Analyze website visits, traffic sources, conversion funnels, search keywords.`
+  );
 
   // traffic overview
   traffic
     .command('overview')
-    .description('Get traffic overview')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--product <id>', 'Filter by product ID')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Traffic overview.
+
+Get page views, unique visitors, sessions, and comparison with previous period.
+
+Returns JSON:
+{
+  "period": { "start": "2024-01-01", "end": "2024-01-30", "days": 30 },
+  "summary": {
+    "page_views": 10000,
+    "unique_visitors": 3000,
+    "sessions": 5000,
+    "avg_session_duration": 180,  // seconds
+    "bounce_rate": 0.35           // 35%
+  },
+  "comparison": {
+    "page_views_change": 0.15,    // +15%
+    "unique_visitors_change": 0.10
+  }
+}
+
+Examples:
+  bi-cli traffic overview                     # Last 30 days, all pages
+  bi-cli traffic overview --days 7            # Last 7 days
+  bi-cli traffic overview --product <uuid>    # Filter by product`
+    )
+    .option('--days <number>', 'Number of days (range: 1-365, default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -129,10 +158,29 @@ export function createTrafficCommand(): Command {
   // traffic sources
   traffic
     .command('sources')
-    .description('Get traffic sources')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '10')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Traffic source analysis.
+
+Analyze visitor sources (Google, WeChat, direct, etc.).
+
+Returns JSON:
+{
+  "sources": [
+    {
+      "source": "google",
+      "medium": "organic",
+      "visitors": 1000,
+      "page_views": 3000,
+      "percentage": 0.35  // 35%
+    }
+  ]
+}
+
+Use case: Evaluate channel effectiveness, optimize marketing spend.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 10)', '10')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -179,10 +227,28 @@ export function createTrafficCommand(): Command {
   // traffic funnel
   traffic
     .command('funnel')
-    .description('Get conversion funnel')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--product <id>', 'Filter by product ID')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Conversion funnel analysis.
+
+Analyze user journey from visit to purchase:
+  Visit → View Product → Add to Cart → Checkout → Purchase
+
+Returns JSON:
+{
+  "funnel": [
+    { "step": "page_view", "count": 10000, "rate": 1.0, "conversion": 1.0 },
+    { "step": "product_view", "count": 5000, "rate": 0.5, "conversion": 0.5 },
+    { "step": "add_to_cart", "count": 1000, "rate": 0.1, "conversion": 0.2 },
+    { "step": "checkout", "count": 500, "rate": 0.05, "conversion": 0.5 },
+    { "step": "purchase", "count": 300, "rate": 0.03, "conversion": 0.6 }
+  ]
+}
+
+Note: rate = ratio from start, conversion = conversion from previous step.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--product <id>', 'Filter by product ID (UUID format)')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -227,11 +293,27 @@ export function createTrafficCommand(): Command {
   // traffic search
   traffic
     .command('search')
-    .description('Get search analytics')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '20')
-    .option('--zero-results', 'Show only zero results queries')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Site search analytics.
+
+Analyze search keywords, result counts, and click-through rates.
+
+Returns JSON:
+{
+  "searches": [
+    { "query": "dress", "count": 500, "avg_results": 25, "click_rate": 0.65 }
+  ],
+  "zero_results": [
+    { "query": "nonexistent product", "count": 10 }
+  ]
+}
+
+Use case: Optimize product titles, add missing products, improve search.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--zero-results', 'Show only zero-result queries')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 
@@ -288,10 +370,28 @@ export function createTrafficCommand(): Command {
   // traffic pages
   traffic
     .command('pages')
-    .description('Get top pages')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--limit <number>', 'Limit results', '20')
-    .option('--pretty', 'Output in pretty format (default: JSON)')
+    .description(
+      `Top pages analysis.
+
+View most popular pages sorted by page views.
+
+Returns JSON:
+{
+  "pages": [
+    {
+      "path": "/products/xxx",
+      "page_views": 5000,
+      "unique_visitors": 2000,
+      "sessions": 3000
+    }
+  ]
+}
+
+Use case: Understand browsing patterns, optimize popular page experience.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--limit <number>', 'Number of results (default: 20)', '20')
+    .option('--pretty', 'Output as table (default: JSON)')
     .action(async (options) => {
       const cfg = getConfig();
 

package/src/commands/trends.ts

@@ -78,15 +78,39 @@ interface ForecastResponse {
 }
 
 export function createTrendsCommand(): Command {
-  const trends = new Command('trends').description('Trend analytics');
+  const trends = new Command('trends').description(
+    `Trend analytics.
+
+Analyze revenue trends, order heatmaps, seasonality, and forecasts.`
+  );
 
   // trends revenue
   trends
     .command('revenue')
-    .description('Get revenue trend over time')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--granularity <type>', 'Granularity: hourly, daily, weekly', 'daily')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Revenue trend analysis.
+
+View revenue over time with hourly/daily/weekly aggregation and 7-day moving average.
+
+Returns JSON:
+{
+  "statistics": {
+    "total_revenue": number,
+    "avg_revenue": number,
+    "trend_direction": "up" | "down" | "stable"
+  },
+  "trend": [
+    { "period": "2024-01-01", "revenue": 1000, "orders": 50, "moving_avg_7": 950 }
+  ]
+}
+
+Examples:
+  bi-cli trends revenue                        # Last 30 days, daily
+  bi-cli trends revenue --days 7 --granularity hourly  # Last 7 days, hourly`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--granularity <type>', 'Time granularity: hourly | daily | weekly', 'daily')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -152,9 +176,25 @@ export function createTrendsCommand(): Command {
   // trends heatmap
   trends
     .command('heatmap')
-    .description('Orders heatmap by day and hour')
-    .option('--days <number>', 'Number of days', '30')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Orders heatmap by day and hour.
+
+Analyze order distribution by day of week and hour to find peak times.
+
+Returns JSON:
+{
+  "heatmap": [
+    { "day": "Monday", "hours": [ { "hour": 10, "orders": 15, "revenue": 500 }, ... ] }
+  ],
+  "peak_times": [
+    { "day": "Saturday", "hour": "14:00-15:00", "orders": 25 }
+  ]
+}
+
+Use case: Optimize marketing timing, schedule customer service staff.`
+    )
+    .option('--days <number>', 'Number of days (default: 30)', '30')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -221,8 +261,26 @@ export function createTrendsCommand(): Command {
   // trends seasonality
   trends
     .command('seasonality')
-    .description('Monthly/seasonal patterns')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Monthly/seasonal pattern analysis.
+
+Analyze sales by month to identify peak and low seasons.
+
+Returns JSON:
+{
+  "monthly_pattern": [
+    { "month": 1, "month_name": "January", "revenue": 50000, "orders": 500, "index": 120 }
+  ],
+  "insights": {
+    "peak_months": ["December", "November"],
+    "low_months": ["February"],
+    "avg_monthly_revenue": 45000
+  }
+}
+
+Note: index is percentage relative to average (>100 = above average).`
+    )
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {
@@ -277,9 +335,28 @@ export function createTrendsCommand(): Command {
   // trends forecast
   trends
     .command('forecast')
-    .description('Revenue forecast')
-    .option('--days <number>', 'Number of days to forecast', '7')
-    .option('--pretty', 'Output in pretty table format')
+    .description(
+      `Revenue forecast.
+
+Predict future revenue based on historical data, considering trends and day-of-week patterns.
+
+Returns JSON:
+{
+  "trend": { "direction": "up", "daily_change": 50.5 },
+  "forecast": [
+    { "date": "2024-01-15", "day_of_week": "Monday", "predicted_revenue": 5000, "confidence": "medium" }
+  ],
+  "disclaimer": "For reference only..."
+}
+
+Note: Forecast based on simple linear model, for reference only.
+
+Examples:
+  bi-cli trends forecast              # Forecast next 7 days
+  bi-cli trends forecast --days 14    # Forecast next 14 days`
+    )
+    .option('--days <number>', 'Days to forecast (default: 7)', '7')
+    .option('--pretty', 'Output as table')
     .action(async (options) => {
       const cfg = getConfig();
       if (!cfg.accessToken) {

package/src/index.ts

@@ -20,7 +20,19 @@ const program = new Command();
 
 program
   .name('bi-cli')
-  .description('Optima BI CLI - AI-friendly business intelligence tool')
+  .description(
+    `Optima BI CLI - E-commerce business intelligence tool for LLM agents.
+
+IMPORTANT: Run 'bi-cli auth login' first to authenticate before using other commands.
+
+Output: All commands output JSON by default (for programmatic parsing). Use --pretty for human-readable tables.
+
+Common use cases:
+  - 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 periods → bi-cli analytics compare --days 7`
+  )
   .version(pkg.version);
 
 // Auth commands
@@ -44,33 +56,33 @@ program.addCommand(createTrafficCommand());
 // Config commands (placeholder)
 program
   .command('config')
-  .description('Manage configuration')
+  .description('[NOT IMPLEMENTED] Configuration management')
   .action(() => {
-    console.log('Config management coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Customer commands (placeholder)
 program
   .command('customer')
-  .description('Customer analytics')
+  .description('[NOT IMPLEMENTED] Customer analytics')
   .action(() => {
-    console.log('Customer analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Inventory commands (placeholder)
 program
   .command('inventory')
-  .description('Inventory analytics')
+  .description('[NOT IMPLEMENTED] Inventory analytics')
   .action(() => {
-    console.log('Inventory analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 // Platform commands (admin only - placeholder)
 program
   .command('platform')
-  .description('Platform analytics (admin only)')
+  .description('[NOT IMPLEMENTED] Platform analytics (admin only)')
   .action(() => {
-    console.log('Platform analytics coming soon...');
+    console.log('This feature is not yet implemented');
   });
 
 program.parse();