@ekkos/cli 0.2.18 → 1.0.0

package/dist/commands/usage/blocks.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blocksCommand = blocksCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage blocks [--json]
+ *
+ * Show 5-hour billing block analysis
+ */
+async function blocksCommand(options) {
+    const data = await (0, usage_parser_js_1.getBucketUsage)();
+    if (data.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        console.log();
+        console.log(chalk_1.default.yellow('  Billing blocks not available.'));
+        console.log(chalk_1.default.gray('  This may be due to a compatibility issue with ccusage v18.'));
+        console.log(chalk_1.default.gray('  Try: npx ccusage blocks'));
+        console.log();
+        return;
+    }
+    // Sort by start time descending
+    const sorted = [...data].sort((a, b) => (b.bucketStart || b.start || b.date || '').localeCompare(a.bucketStart || a.start || a.date || ''));
+    const recent = sorted.slice(0, 20);
+    if (options.json) {
+        console.log(JSON.stringify(recent, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Billing Blocks (5-Hour Windows)');
+    const maxCost = Math.max(...recent.map(b => b.totalCost || b.cost || 0));
+    console.log(chalk_1.default.gray('  Block Start'.padEnd(22)) +
+        chalk_1.default.gray('│ ') +
+        chalk_1.default.gray('Cost'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Input'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Output'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Models'.padEnd(12)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Chart'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    for (const block of recent) {
+        const cost = block.totalCost || block.cost || 0;
+        const start = (0, formatters_js_1.formatTimestamp)(block.bucketStart || block.start || block.date || '');
+        const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 12);
+        const models = (block.modelsUsed || []).length;
+        console.log(`  ${chalk_1.default.white(start.padEnd(20))} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(block.inputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(block.outputTokens || 0).padStart(8)} │ ${chalk_1.default.cyan(models.toString().padStart(2))} models  │ ${bar}`);
+    }
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/daily.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ekkos usage daily [--days N] [--json]
+ *
+ * Show daily usage breakdown
+ */
+export declare function dailyCommand(options: {
+    days?: number;
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/usage/daily.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dailyCommand = dailyCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage daily [--days N] [--json]
+ *
+ * Show daily usage breakdown
+ */
+async function dailyCommand(options) {
+    const days = options.days || 14;
+    const data = await (0, usage_parser_js_1.getDailyUsage)();
+    if (data.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('daily usage');
+        return;
+    }
+    // Sort by date descending (most recent first)
+    const sorted = [...data].sort((a, b) => b.date.localeCompare(a.date));
+    const recent = sorted.slice(0, days);
+    if (options.json) {
+        console.log(JSON.stringify(recent, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Daily Usage Report', `Last ${Math.min(days, recent.length)} days`);
+    // Find max cost for bar chart scaling
+    const maxCost = Math.max(...recent.map(d => d.totalCost || d.cost || 0));
+    let totalCost = 0;
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCacheRead = 0;
+    let totalCacheCreation = 0;
+    // Table header
+    console.log(chalk_1.default.gray('  Date'.padEnd(16)) +
+        chalk_1.default.gray('│ ') +
+        chalk_1.default.gray('Cost'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Input'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Output'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Cache'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Chart'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    for (const day of recent) {
+        const cost = day.totalCost || day.cost || 0;
+        const date = (0, formatters_js_1.formatDate)(day.date);
+        const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 20);
+        totalCost += cost;
+        totalInput += day.inputTokens || 0;
+        totalOutput += day.outputTokens || 0;
+        totalCacheRead += day.cacheReadTokens || 0;
+        totalCacheCreation += day.cacheCreationTokens || 0;
+        // Highlight today
+        const isToday = day.date === new Date().toISOString().split('T')[0];
+        const dateStr = isToday ? chalk_1.default.bold.cyan(date.padEnd(14)) : chalk_1.default.white(date.padEnd(14));
+        console.log(`  ${dateStr} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(day.inputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(day.outputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(day.cacheReadTokens || 0).padStart(8)} │ ${bar}`);
+    }
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(chalk_1.default.bold('  TOTAL'.padEnd(16)) +
+        `│ ${chalk_1.default.green.bold((0, formatters_js_1.formatCost)(totalCost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(totalInput).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(totalOutput).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(totalCacheRead).padStart(8)} │`);
+    console.log();
+    // Model breakdown for the period
+    const allBreakdowns = recent.flatMap(d => d.modelBreakdowns || []);
+    if (allBreakdowns.length > 0) {
+        // Aggregate by model
+        const byModel = new Map();
+        for (const b of allBreakdowns) {
+            const existing = byModel.get(b.modelName);
+            if (existing) {
+                existing.inputTokens += b.inputTokens || 0;
+                existing.outputTokens += b.outputTokens || 0;
+                existing.cacheCreationTokens += b.cacheCreationTokens || 0;
+                existing.cacheReadTokens += b.cacheReadTokens || 0;
+                existing.cost += b.cost || 0;
+            }
+            else {
+                byModel.set(b.modelName, { ...b });
+            }
+        }
+        (0, formatters_js_1.sectionHeader)('Models Used');
+        (0, formatters_js_1.printModelBreakdowns)([...byModel.values()].sort((a, b) => b.cost - a.cost));
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/dashboard.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ekkos usage dashboard [--json]
+ *
+ * Rich composite dashboard showing today, this week, this month + trends
+ */
+export declare function dashboardCommand(options: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/usage/dashboard.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardCommand = dashboardCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage dashboard [--json]
+ *
+ * Rich composite dashboard showing today, this week, this month + trends
+ */
+async function dashboardCommand(options) {
+    // Load all data in parallel
+    const [daily, monthly, sessions] = await Promise.all([
+        (0, usage_parser_js_1.getDailyUsage)(),
+        (0, usage_parser_js_1.getMonthlyUsage)(),
+        (0, usage_parser_js_1.getAllSessions)(),
+    ]);
+    if (daily.length === 0 && monthly.length === 0 && sessions.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ daily: [], monthly: [], sessions: [] }));
+            return;
+        }
+        (0, formatters_js_1.noData)('usage');
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ daily, monthly, sessions }, null, 2));
+        return;
+    }
+    const now = new Date();
+    const todayStr = now.toISOString().split('T')[0];
+    const dateDisplay = now.toLocaleDateString('en-US', {
+        weekday: 'long',
+        month: 'long',
+        day: 'numeric',
+        year: 'numeric'
+    });
+    (0, formatters_js_1.titleBar)('ekkOS Usage Dashboard', dateDisplay);
+    // ── TODAY / THIS WEEK / THIS MONTH summary ──
+    const sortedDaily = [...daily].sort((a, b) => b.date.localeCompare(a.date));
+    const today = sortedDaily.find(d => d.date === todayStr);
+    const last7 = sortedDaily.filter(d => {
+        const dDate = new Date(d.date);
+        const diff = (now.getTime() - dDate.getTime()) / (1000 * 60 * 60 * 24);
+        return diff <= 7;
+    });
+    const thisMonthStr = todayStr.substring(0, 7); // "2026-02"
+    const sortedMonthly = [...monthly].sort((a, b) => (b.month || '').localeCompare(a.month || ''));
+    const thisMonth = sortedMonthly.find(m => (m.month || '').startsWith(thisMonthStr));
+    const todayCost = today ? (today.totalCost || today.cost || 0) : 0;
+    const weekCost = last7.reduce((sum, d) => sum + (d.totalCost || d.cost || 0), 0);
+    const monthCost = thisMonth ? (thisMonth.totalCost || thisMonth.cost || 0) : 0;
+    const todayTokens = today ? (today.inputTokens || 0) + (today.outputTokens || 0) + (today.cacheReadTokens || 0) + (today.cacheCreationTokens || 0) : 0;
+    const weekTokens = last7.reduce((sum, d) => sum + (d.inputTokens || 0) + (d.outputTokens || 0) + (d.cacheReadTokens || 0) + (d.cacheCreationTokens || 0), 0);
+    const monthTokens = thisMonth ? (thisMonth.inputTokens || 0) + (thisMonth.outputTokens || 0) + (thisMonth.cacheReadTokens || 0) + (thisMonth.cacheCreationTokens || 0) : 0;
+    console.log(`  ${chalk_1.default.bold('TODAY')}                          ${chalk_1.default.bold('THIS WEEK')}                ${chalk_1.default.bold('THIS MONTH')}`);
+    console.log(`  ${chalk_1.default.gray('─────')}                          ${chalk_1.default.gray('─────────')}                ${chalk_1.default.gray('──────────')}`);
+    console.log(`  Cost:   ${chalk_1.default.green((0, formatters_js_1.formatCost)(todayCost).padEnd(16))}     Cost:   ${chalk_1.default.green((0, formatters_js_1.formatCost)(weekCost).padEnd(16))}  Cost:   ${chalk_1.default.green((0, formatters_js_1.formatCost)(monthCost))}`);
+    console.log(`  Tokens: ${(0, formatters_js_1.formatCompact)(todayTokens).padEnd(16)}     Tokens: ${(0, formatters_js_1.formatCompact)(weekTokens).padEnd(16)}  Tokens: ${(0, formatters_js_1.formatCompact)(monthTokens)}`);
+    console.log();
+    // ── TOP MODELS TODAY ──
+    if (today && today.modelBreakdowns && today.modelBreakdowns.length > 0) {
+        (0, formatters_js_1.sectionHeader)('Top Models Today');
+        (0, formatters_js_1.printModelBreakdowns)([...today.modelBreakdowns].sort((a, b) => b.cost - a.cost).slice(0, 5));
+        console.log();
+    }
+    // ── DAILY TREND (last 7 days) ──
+    if (sortedDaily.length > 0) {
+        (0, formatters_js_1.sectionHeader)('Daily Trend (7 days)');
+        const trend = sortedDaily.slice(0, 7).reverse(); // oldest first for chart
+        const maxCost = Math.max(...trend.map(d => d.totalCost || d.cost || 0));
+        for (const day of trend) {
+            const cost = day.totalCost || day.cost || 0;
+            const date = new Date(day.date);
+            const dayName = date.toLocaleDateString('en-US', { weekday: 'short' });
+            const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 20);
+            const isToday = day.date === todayStr;
+            const marker = isToday ? chalk_1.default.cyan(' <- today') : '';
+            console.log(`  ${chalk_1.default.white(dayName)} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(8))}  ${bar}${marker}`);
+        }
+        console.log();
+    }
+    // ── RECENT SESSIONS (top 5 by cost) ──
+    if (sessions.length > 0) {
+        (0, formatters_js_1.sectionHeader)('Top Sessions by Cost');
+        const topSessions = [...sessions]
+            .sort((a, b) => (b.total_cost || 0) - (a.total_cost || 0))
+            .slice(0, 5);
+        for (const s of topSessions) {
+            const name = s.session_name || s.session_id;
+            const cost = (0, formatters_js_1.formatCost)(s.total_cost);
+            const tokens = (0, formatters_js_1.formatCompact)(s.total_tokens);
+            const models = s.models_used.slice(0, 2).join(', ');
+            console.log(`  ${chalk_1.default.bold(name.padEnd(30))} │ ${chalk_1.default.green(cost.padStart(10))} │ ${tokens.padStart(8)} tokens │ ${chalk_1.default.cyan(models)}`);
+        }
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/formatters.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared formatting utilities for all usage subcommands
+ */
+/** Format numbers with commas */
+export declare function formatNumber(num: number): string;
+/** Format as compact number (1.2M, 45K, etc.) */
+export declare function formatCompact(num: number): string;
+/** Format percentage */
+export declare function formatPercentage(pct: number): string;
+/** Format cost in USD */
+export declare function formatCost(cost: number): string;
+/** Format timestamp to readable string */
+export declare function formatTimestamp(ts: string): string;
+/** Format date only */
+export declare function formatDate(ts: string): string;
+/** Get color function for context percentage */
+export declare function getContextColor(pct: number): (str: string) => string;
+/** Render a horizontal bar chart */
+export declare function renderBar(value: number, maxValue: number, width?: number): string;
+/** Print a section header */
+export declare function sectionHeader(title: string): void;
+/** Print the main title bar */
+export declare function titleBar(title: string, subtitle?: string): void;
+/** Format token breakdown inline */
+export declare function formatTokensInline(data: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+}): string;
+/** Print model breakdown table */
+export declare function printModelBreakdowns(breakdowns: {
+    modelName: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    cost: number;
+}[]): void;
+/** Print "no data" message */
+export declare function noData(what: string): void;

package/dist/commands/usage/formatters.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNumber = formatNumber;
+exports.formatCompact = formatCompact;
+exports.formatPercentage = formatPercentage;
+exports.formatCost = formatCost;
+exports.formatTimestamp = formatTimestamp;
+exports.formatDate = formatDate;
+exports.getContextColor = getContextColor;
+exports.renderBar = renderBar;
+exports.sectionHeader = sectionHeader;
+exports.titleBar = titleBar;
+exports.formatTokensInline = formatTokensInline;
+exports.printModelBreakdowns = printModelBreakdowns;
+exports.noData = noData;
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Shared formatting utilities for all usage subcommands
+ */
+/** Format numbers with commas */
+function formatNumber(num) {
+    if (num === undefined || num === null || isNaN(num))
+        return '0';
+    return num.toLocaleString('en-US');
+}
+/** Format as compact number (1.2M, 45K, etc.) */
+function formatCompact(num) {
+    if (num === undefined || num === null || isNaN(num))
+        return '0';
+    if (num >= 1000000000)
+        return `${(num / 1000000000).toFixed(1)}B`;
+    if (num >= 1000000)
+        return `${(num / 1000000).toFixed(1)}M`;
+    if (num >= 1000)
+        return `${(num / 1000).toFixed(1)}K`;
+    return num.toString();
+}
+/** Format percentage */
+function formatPercentage(pct) {
+    if (pct === undefined || pct === null || isNaN(pct))
+        return '0.0%';
+    return `${pct.toFixed(1)}%`;
+}
+/** Format cost in USD */
+function formatCost(cost) {
+    if (cost === undefined || cost === null || isNaN(cost))
+        return '$0.00';
+    return `$${cost.toFixed(2)}`;
+}
+/** Format timestamp to readable string */
+function formatTimestamp(ts) {
+    try {
+        const date = new Date(ts);
+        if (isNaN(date.getTime()))
+            return ts;
+        return date.toLocaleString('en-US', {
+            month: 'short',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: '2-digit',
+            hour12: true
+        });
+    }
+    catch {
+        return ts;
+    }
+}
+/** Format date only */
+function formatDate(ts) {
+    try {
+        const date = new Date(ts);
+        if (isNaN(date.getTime()))
+            return ts;
+        return date.toLocaleDateString('en-US', {
+            weekday: 'short',
+            month: 'short',
+            day: 'numeric'
+        });
+    }
+    catch {
+        return ts;
+    }
+}
+/** Get color function for context percentage */
+function getContextColor(pct) {
+    if (pct < 30)
+        return chalk_1.default.green;
+    if (pct < 50)
+        return chalk_1.default.yellow;
+    if (pct < 70)
+        return chalk_1.default.hex('#FFA500');
+    return chalk_1.default.red;
+}
+/** Render a horizontal bar chart */
+function renderBar(value, maxValue, width = 16) {
+    if (maxValue === 0)
+        return '░'.repeat(width);
+    const filled = Math.round((value / maxValue) * width);
+    const empty = width - filled;
+    return '█'.repeat(Math.max(0, filled)) + '░'.repeat(Math.max(0, empty));
+}
+/** Print a section header */
+function sectionHeader(title) {
+    console.log(chalk_1.default.bold(title));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+}
+/** Print the main title bar */
+function titleBar(title, subtitle) {
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    if (subtitle) {
+        console.log(chalk_1.default.bold.cyan(`  ${title}`) + chalk_1.default.gray(`  ${subtitle}`));
+    }
+    else {
+        console.log(chalk_1.default.bold.cyan(`  ${title}`));
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}
+/** Format token breakdown inline */
+function formatTokensInline(data) {
+    return `In: ${formatCompact(data.inputTokens)} Out: ${formatCompact(data.outputTokens)} Cache: ${formatCompact(data.cacheReadTokens)}`;
+}
+/** Print model breakdown table */
+function printModelBreakdowns(breakdowns) {
+    if (!breakdowns || breakdowns.length === 0)
+        return;
+    const totalCost = breakdowns.reduce((sum, b) => sum + (b.cost || 0), 0);
+    for (const b of breakdowns) {
+        const pct = totalCost > 0 ? (b.cost / totalCost) * 100 : 0;
+        const totalTokens = (b.inputTokens || 0) + (b.outputTokens || 0) +
+            (b.cacheCreationTokens || 0) + (b.cacheReadTokens || 0);
+        const name = (b.modelName || 'unknown').padEnd(32);
+        const bar = renderBar(b.cost, totalCost);
+        console.log(`  ${chalk_1.default.cyan(name)} │ ${formatCompact(totalTokens).padStart(7)} tokens │ ${chalk_1.default.green(formatCost(b.cost).padStart(8))} │ ${bar} ${pct.toFixed(0).padStart(3)}%`);
+    }
+}
+/** Print "no data" message */
+function noData(what) {
+    console.log();
+    console.log(chalk_1.default.yellow(`  No ${what} data found.`));
+    console.log(chalk_1.default.gray('  Make sure you have Claude Code sessions in ~/.claude/projects/'));
+    console.log();
+}

package/dist/commands/usage/index.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+/**
+ * Register usage subcommand tree on the main program
+ *
+ * ekkos usage                  → dashboard (default)
+ * ekkos usage daily            → daily report
+ * ekkos usage weekly           → weekly report
+ * ekkos usage monthly          → monthly report
+ * ekkos usage blocks           → 5-hour billing blocks
+ * ekkos usage session [id]     → session detail / list
+ * ekkos usage dashboard        → rich composite view
+ */
+export declare function registerUsageCommand(program: Command): void;

package/dist/commands/usage/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUsageCommand = registerUsageCommand;
+const daily_js_1 = require("./daily.js");
+const weekly_js_1 = require("./weekly.js");
+const monthly_js_1 = require("./monthly.js");
+const blocks_js_1 = require("./blocks.js");
+const dashboard_js_1 = require("./dashboard.js");
+const session_js_1 = require("./session.js");
+/**
+ * Register usage subcommand tree on the main program
+ *
+ * ekkos usage                  → dashboard (default)
+ * ekkos usage daily            → daily report
+ * ekkos usage weekly           → weekly report
+ * ekkos usage monthly          → monthly report
+ * ekkos usage blocks           → 5-hour billing blocks
+ * ekkos usage session [id]     → session detail / list
+ * ekkos usage dashboard        → rich composite view
+ */
+function registerUsageCommand(program) {
+    const usageCmd = program
+        .command('usage')
+        .description('Track Claude Code token usage and costs (powered by ccusage)')
+        .action(async (options) => {
+        // Default: show dashboard when no subcommand given
+        await (0, dashboard_js_1.dashboardCommand)({ json: options.json });
+    })
+        .option('-j, --json', 'Output machine-readable JSON');
+    // Daily subcommand
+    usageCmd
+        .command('daily')
+        .description('Daily usage breakdown')
+        .option('-d, --days <n>', 'Number of days to show', '14')
+        .option('-j, --json', 'Output JSON')
+        .action(async (options) => {
+        await (0, daily_js_1.dailyCommand)({ days: parseInt(options.days, 10), json: options.json });
+    });
+    // Weekly subcommand
+    usageCmd
+        .command('weekly')
+        .description('Weekly usage breakdown')
+        .option('-w, --weeks <n>', 'Number of weeks to show', '8')
+        .option('-j, --json', 'Output JSON')
+        .action(async (options) => {
+        await (0, weekly_js_1.weeklyCommand)({ weeks: parseInt(options.weeks, 10), json: options.json });
+    });
+    // Monthly subcommand
+    usageCmd
+        .command('monthly')
+        .description('Monthly usage breakdown')
+        .option('-j, --json', 'Output JSON')
+        .action(async (options) => {
+        await (0, monthly_js_1.monthlyCommand)({ json: options.json });
+    });
+    // Blocks subcommand (5-hour billing windows)
+    usageCmd
+        .command('blocks')
+        .description('5-hour billing block analysis')
+        .option('-j, --json', 'Output JSON')
+        .action(async (options) => {
+        await (0, blocks_js_1.blocksCommand)({ json: options.json });
+    });
+    // Session subcommand
+    usageCmd
+        .command('session [session-id]')
+        .description('Session usage detail or list all sessions')
+        .option('-l, --list', 'List all sessions')
+        .option('-i, --instance <id>', 'Instance ID (project path)')
+        .option('-j, --json', 'Output JSON')
+        .action(async (sessionId, options) => {
+        await (0, session_js_1.sessionCommand)({
+            sessionId,
+            list: options.list,
+            instance: options.instance,
+            json: options.json,
+        });
+    });
+    // Dashboard subcommand (explicit)
+    usageCmd
+        .command('dashboard')
+        .description('Rich composite usage dashboard')
+        .option('-j, --json', 'Output JSON')
+        .action(async (options) => {
+        await (0, dashboard_js_1.dashboardCommand)({ json: options.json });
+    });
+}

package/dist/commands/usage/monthly.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ekkos usage monthly [--json]
+ *
+ * Show monthly usage breakdown
+ */
+export declare function monthlyCommand(options: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/usage/monthly.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.monthlyCommand = monthlyCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage monthly [--json]
+ *
+ * Show monthly usage breakdown
+ */
+async function monthlyCommand(options) {
+    const data = await (0, usage_parser_js_1.getMonthlyUsage)();
+    if (data.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('monthly usage');
+        return;
+    }
+    // Sort by month descending
+    const sorted = [...data].sort((a, b) => (b.month || '').localeCompare(a.month || ''));
+    if (options.json) {
+        console.log(JSON.stringify(sorted, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Monthly Usage Report');
+    const maxCost = Math.max(...sorted.map(m => m.totalCost || m.cost || 0));
+    let grandTotal = 0;
+    console.log(chalk_1.default.gray('  Month'.padEnd(16)) +
+        chalk_1.default.gray('│ ') +
+        chalk_1.default.gray('Cost'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Input'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Output'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Cache Read'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Chart'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    for (const month of sorted) {
+        const cost = month.totalCost || month.cost || 0;
+        grandTotal += cost;
+        const label = month.month || 'unknown';
+        const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 14);
+        console.log(`  ${chalk_1.default.white(label.padEnd(14))} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(month.inputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(month.outputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(month.cacheReadTokens || 0).padStart(10)} │ ${bar}`);
+        // Show model breakdown per month
+        if (month.modelBreakdowns && month.modelBreakdowns.length > 0) {
+            for (const b of month.modelBreakdowns.sort((a, b) => b.cost - a.cost)) {
+                const name = (b.modelName || 'unknown').substring(0, 28);
+                console.log(chalk_1.default.gray(`    ${name.padEnd(30)} ${(0, formatters_js_1.formatCost)(b.cost).padStart(10)}`));
+            }
+        }
+    }
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(chalk_1.default.bold('  GRAND TOTAL'.padEnd(16)) +
+        `│ ${chalk_1.default.green.bold((0, formatters_js_1.formatCost)(grandTotal).padStart(10))} │`);
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/session.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ekkos usage session [id] [--list] [--instance id] [--json]
+ *
+ * Accepts ekkOS 3-word names (lit-lex-zip) or ccusage project paths.
+ */
+export declare function sessionCommand(options: {
+    sessionId?: string;
+    list?: boolean;
+    instance?: string;
+    json?: boolean;
+}): Promise<void>;