@optima-chat/merchant-cli

BI and analytics CLI tool for Optima merchants

Overview

optima-merchant is a command-line BI tool designed for Optima merchants to analyze their business data, track sales performance, manage inventory, and gain insights into customer behavior.

Key Features:

• 📊 Sales Analytics - Track revenue, orders, trends, and growth
• 📦 Product Analysis - Identify top-selling and slow-moving products
• 🚚 Order Operations - Monitor order fulfillment and status
• 💰 Financial Reporting - View income, transfers, and platform fees
• 👥 Customer Insights - Analyze customer behavior and segmentation

Installation

npm install -g @optima-chat/merchant-cli
# or
pnpm add -g @optima-chat/merchant-cli

Quick Start

Authentication

First, authenticate using your Optima account:

# Login (uses optima-cli for authentication)
optima-cli auth login

# Or set token directly
export OPTIMA_TOKEN=<your-token>

Basic Commands

# View sales summary for current month
optima-merchant sales summary

# View today's sales
optima-merchant sales today

# List top 10 selling products
optima-merchant products top-selling --limit 10

# Check pending orders
optima-merchant orders pending

# View financial summary
optima-merchant finance summary

Commands

Sales Analysis

# Sales summary
optima-merchant sales summary [--month YYYY-MM]

# Today's sales
optima-merchant sales today

# Compare time periods
optima-merchant sales compare --from YYYY-MM --to YYYY-MM

# Sales trend chart
optima-merchant sales trend [--days 30]

Product Analysis

# Top-selling products
optima-merchant products top-selling [--limit 10] [--period 30d]

# Slow-moving products
optima-merchant products slow-moving [--days 60]

# Out of stock products
optima-merchant products out-of-stock

# Product inventory status
optima-merchant products inventory

Order Operations

# Pending orders
optima-merchant orders pending

# Fulfillment efficiency
optima-merchant orders fulfillment [--period 30d]

# Order status distribution
optima-merchant orders status

# Cancellation analysis
optima-merchant orders cancellation

Financial Reporting

# Financial summary
optima-merchant finance summary [--month YYYY-MM]

# Pending transfers
optima-merchant finance pending-transfers

# Platform fees
optima-merchant finance platform-fees [--period 30d]

# Export financial data
optima-merchant finance export --format csv --output finance.csv

Customer Analysis

# Customer analysis
optima-merchant customers analyze

# High-value customers
optima-merchant customers high-value [--min-ltv 1000]

# Customer retention
optima-merchant customers retention

# Customer segmentation
optima-merchant customers segmentation

Output Formats

JSON (Default - AI Friendly)

$ optima-merchant sales summary
{
  "success": true,
  "data": {
    "period": "2025-10",
    "metrics": {
      "total_revenue": 125000.50,
      "total_orders": 342,
      "avg_order_value": 365.50,
      "growth_rate": 15.3
    }
  }
}

Pretty (Human Friendly)

$ optima-merchant sales summary --pretty

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Sales Summary - October 2025
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Total Revenue    $125,000.50  ↑ 15.3%
  Total Orders     342          ↑ 8.2%
  Avg Order Value  $365.50      ↑ 6.5%

CSV Export

$ optima-merchant finance summary --export finance.csv

Environment Variables

# Authentication token (highest priority)
OPTIMA_TOKEN=<token>

# API endpoints
OPTIMA_API_URL=https://api.optima.shop
OPTIMA_AUTH_URL=https://auth.optima.shop

# Output format
OPTIMA_OUTPUT_FORMAT=json|pretty

# AI mode
OPTIMA_AI_MODE=true

# Debug logging
DEBUG=optima:*

AI-Friendly Design

This CLI is optimized for AI assistants like Claude Code:

• Default JSON output for easy parsing
• Structured error messages with error codes
• Rich help text with examples
• Non-interactive mode when running in AI environments

Example with Claude Code:

User: "Show me my sales for October"

Claude: optima-merchant sales summary --month 2025-10

Development

# Clone repository
git clone https://github.com/Optima-Chat/optima-merchant-cli.git
cd optima-merchant-cli

# Install dependencies
pnpm install

# Build
pnpm build

# Link for local testing
pnpm link

# Run tests
pnpm test

Architecture

See the Architecture Documentation for detailed design.

Contributing

Please read our Contributing Guide.

License

MIT © Optima Development Team

Links

• Documentation
• GitHub
• NPM
• Issues