ccusage 0.5.0 → 0.6.0

package/README.md

@@ -38,12 +38,13 @@ This tool helps you understand the value you're getting from your subscription b
 ## Features
 
 - 📊 **Daily Report**: View token usage and costs aggregated by date
+- 📅 **Monthly Report**: View token usage and costs aggregated by month
 - 💬 **Session Report**: View usage grouped by conversation sessions
 - 📅 **Date Filtering**: Filter reports by date range using `--since` and `--until`
 - 📁 **Custom Path**: Support for custom Claude data directory locations
 - 🎨 **Beautiful Output**: Colorful table-formatted display
 - 📄 **JSON Output**: Export data in structured JSON format with `--json`
-- 💰 **Cost Tracking**: Shows costs in USD for each day/session
+- 💰 **Cost Tracking**: Shows costs in USD for each day/month/session
 - 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
 
 ## Important Disclaimer
@@ -134,10 +135,41 @@ ccusage daily --json
 ccusage daily --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage daily --mode calculate  # Always calculate costs from tokens
 ccusage daily --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage daily --order asc       # Show oldest dates first
+ccusage daily --order desc      # Show newest dates first (default)
 ```
 
 `ccusage` is an alias for `ccusage daily`, so you can run it without specifying the subcommand.
 
+### Monthly Report
+
+Shows token usage and costs aggregated by month:
+
+```bash
+# Show all monthly usage
+ccusage monthly
+
+# Filter by date range
+ccusage monthly --since 20250101 --until 20250531
+
+# Use custom Claude data directory
+ccusage monthly --path /custom/path/to/.claude
+
+# Output in JSON format
+ccusage monthly --json
+
+# Control cost calculation mode
+ccusage monthly --mode auto       # Use costUSD when available, calculate otherwise (default)
+ccusage monthly --mode calculate  # Always calculate costs from tokens
+ccusage monthly --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage monthly --order asc       # Show oldest months first
+ccusage monthly --order desc      # Show newest months first (default)
+```
+
 ### Session Report
 
 Shows usage grouped by conversation sessions, sorted by cost:
@@ -159,6 +191,10 @@ ccusage session --json
 ccusage session --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage session --mode calculate  # Always calculate costs from tokens
 ccusage session --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage session --order asc       # Show oldest sessions first
+ccusage session --order desc      # Show newest sessions first (default)
 ```
 
 ### Options
@@ -170,6 +206,7 @@ All commands support the following options:
 - `-p, --path <path>`: Custom path to Claude data directory (default: `~/.claude`)
 - `-j, --json`: Output results in JSON format instead of table
 - `-m, --mode <mode>`: Cost calculation mode: `auto` (default), `calculate`, or `display`
+- `-o, --order <order>`: Sort order: `desc` (newest first, default) or `asc` (oldest first).
 - `-d, --debug`: Show pricing mismatch information for debugging
 - `--debug-samples <number>`: Number of sample discrepancies to show in debug output (default: 5)
 - `-h, --help`: Display help message

package/dist/calculate-cost.d.ts

@@ -1,10 +1,10 @@
 import "./index-BurjgCfW.js";
 import "./pricing-fetcher-DygIroMj.js";
-import { TokenData, TokenTotals } from "./types-B3ib19os.js";
-import { DailyUsage, SessionUsage } from "./data-loader-LMCrJ-lW.js";
+import { TokenData, TokenTotals } from "./types-y1JQzaKZ.js";
+import { DailyUsage, MonthlyUsage, SessionUsage } from "./data-loader-aUOjeZ06.js";
 
 //#region src/calculate-cost.d.ts
-declare function calculateTotals(data: Array<DailyUsage | SessionUsage>): TokenTotals;
+declare function calculateTotals(data: Array<DailyUsage | MonthlyUsage | SessionUsage>): TokenTotals;
 declare function getTotalTokens(tokens: TokenData): number;
 declare function createTotalsObject(totals: TokenTotals): {
   inputTokens: number;

package/dist/{data-loader-r5ZcMQy7.js → data-loader-CDv0IYZx.js}

@@ -1,5 +1,5 @@
-import { array, number, object, optional, safeParse, string } from "./dist-FwNhpFrW.js";
-import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-B5yPtoTB.js";
+import { array, number, object, optional, pipe, regex, safeParse, string } from "./dist-FwNhpFrW.js";
+import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-BCv1Vods.js";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -2110,9 +2110,9 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 		if (glob$1 === "" || typeof glob$1 !== "string" && !isState) throw new TypeError("Expected pattern to be a non-empty string");
 		const opts = options || {};
 		const posix$1 = opts.windows;
-		const regex = isState ? picomatch$2.compileRe(glob$1, options) : picomatch$2.makeRe(glob$1, options, false, true);
-		const state = regex.state;
-		delete regex.state;
+		const regex$1 = isState ? picomatch$2.compileRe(glob$1, options) : picomatch$2.makeRe(glob$1, options, false, true);
+		const state = regex$1.state;
+		delete regex$1.state;
 		let isIgnored = () => false;
 		if (opts.ignore) {
 			const ignoreOpts = {
@@ -2124,14 +2124,14 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 			isIgnored = picomatch$2(opts.ignore, ignoreOpts, returnState);
 		}
 		const matcher = (input, returnObject = false) => {
-			const { isMatch, match, output } = picomatch$2.test(input, regex, options, {
+			const { isMatch, match, output } = picomatch$2.test(input, regex$1, options, {
 				glob: glob$1,
 				posix: posix$1
 			});
 			const result = {
 				glob: glob$1,
 				state,
-				regex,
+				regex: regex$1,
 				posix: posix$1,
 				input,
 				output,
@@ -2170,7 +2170,7 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 	* @return {Object} Returns an object with matching info.
 	* @api public
 	*/
-	picomatch$2.test = (input, regex, options, { glob: glob$1, posix: posix$1 } = {}) => {
+	picomatch$2.test = (input, regex$1, options, { glob: glob$1, posix: posix$1 } = {}) => {
 		if (typeof input !== "string") throw new TypeError("Expected input to be a string");
 		if (input === "") return {
 			isMatch: false,
@@ -2184,8 +2184,8 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 			output = format ? format(input) : input;
 			match = output === glob$1;
 		}
-		if (match === false || opts.capture === true) if (opts.matchBase === true || opts.basename === true) match = picomatch$2.matchBase(input, regex, options, posix$1);
-		else match = regex.exec(output);
+		if (match === false || opts.capture === true) if (opts.matchBase === true || opts.basename === true) match = picomatch$2.matchBase(input, regex$1, options, posix$1);
+		else match = regex$1.exec(output);
 		return {
 			isMatch: Boolean(match),
 			match,
@@ -2206,8 +2206,8 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 	* @api public
 	*/
 	picomatch$2.matchBase = (input, glob$1, options) => {
-		const regex = glob$1 instanceof RegExp ? glob$1 : picomatch$2.makeRe(glob$1, options);
-		return regex.test(utils$1.basename(input));
+		const regex$1 = glob$1 instanceof RegExp ? glob$1 : picomatch$2.makeRe(glob$1, options);
+		return regex$1.test(utils$1.basename(input));
 	};
 	/**
 	* Returns true if **any** of the given glob `patterns` match the specified `string`.
@@ -2291,9 +2291,9 @@ var require_picomatch$1 = __commonJS({ "node_modules/picomatch/lib/picomatch.js"
 		const append = opts.contains ? "" : "$";
 		let source = `${prepend}(?:${state.output})${append}`;
 		if (state && state.negated === true) source = `^(?!${source}).*$`;
-		const regex = picomatch$2.toRegex(source, options);
-		if (returnState === true) regex.state = state;
-		return regex;
+		const regex$1 = picomatch$2.toRegex(source, options);
+		if (returnState === true) regex$1.state = state;
+		return regex$1;
 	};
 	/**
 	* Create a regular expression from a parsed glob pattern.
@@ -2573,14 +2573,14 @@ function getPartialMatcher(patterns, options) {
 		if (inputParts[0] === ".." && ONLY_PARENT_DIRECTORIES.test(input)) return true;
 		for (let i = 0; i < patterns.length; i++) {
 			const patternParts = patternsParts[i];
-			const regex = regexes[i];
+			const regex$1 = regexes[i];
 			const inputPatternCount = inputParts.length;
 			const minParts = Math.min(inputPatternCount, patternParts.length);
 			let j = 0;
 			while (j < minParts) {
 				const part = patternParts[j];
 				if (part.includes("/")) return true;
-				const match = regex[j].test(inputParts[j]);
+				const match = regex$1[j].test(inputParts[j]);
 				if (!match) break;
 				if (part === "**") return true;
 				j++;
@@ -2786,7 +2786,7 @@ const UsageDataSchema = object({
 	costUSD: optional(number())
 });
 const DailyUsageSchema = object({
-	date: string(),
+	date: pipe(string(), regex(/^\d{4}-\d{2}-\d{2}$/)),
 	inputTokens: number(),
 	outputTokens: number(),
 	cacheCreationTokens: number(),
@@ -2804,6 +2804,14 @@ const SessionUsageSchema = object({
 	lastActivity: string(),
 	versions: array(string())
 });
+const MonthlyUsageSchema = object({
+	month: pipe(string(), regex(/^\d{4}-\d{2}$/)),
+	inputTokens: number(),
+	outputTokens: number(),
+	cacheCreationTokens: number(),
+	cacheReadTokens: number(),
+	totalCost: number()
+});
 const formatDate = (dateStr) => {
 	const date = new Date(dateStr);
 	const year = date.getFullYear();
@@ -2827,7 +2835,7 @@ const calculateCostForEntry = (data, mode, modelPricing) => {
 	}
 	return 0;
 };
-async function loadUsageData(options) {
+async function loadDailyUsageData(options) {
 	const claudePath = options?.claudePath ?? getDefaultClaudePath();
 	const claudeDir = path.join(claudePath, "projects");
 	const files = await glob(["**/*.jsonl"], {
@@ -2871,7 +2879,9 @@ async function loadUsageData(options) {
 		if (options.until && dateStr > options.until) return false;
 		return true;
 	});
-	return sort(results).desc((item) => new Date(item.date).getTime());
+	const sortOrder = options?.order || "desc";
+	const sortedResults = sort(results);
+	return sortOrder === "desc" ? sortedResults.desc((item) => new Date(item.date).getTime()) : sortedResults.asc((item) => new Date(item.date).getTime());
 }
 async function loadSessionData(options) {
 	const claudePath = options?.claudePath ?? getDefaultClaudePath();
@@ -2937,8 +2947,35 @@ async function loadSessionData(options) {
 		if (options.until && dateStr > options.until) return false;
 		return true;
 	});
-	return sort(results).desc((item) => new Date(item.lastActivity).getTime());
+	const sortOrder = options?.order || "desc";
+	const sortedResults = sort(results);
+	return sortOrder === "desc" ? sortedResults.desc((item) => new Date(item.lastActivity).getTime()) : sortedResults.asc((item) => new Date(item.lastActivity).getTime());
+}
+async function loadMonthlyUsageData(options) {
+	const dailyData = await loadDailyUsageData(options);
+	const monthlyMap = new Map();
+	for (const data of dailyData) {
+		const month = data.date.substring(0, 7);
+		const existing = monthlyMap.get(month) || {
+			month,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheCreationTokens: 0,
+			cacheReadTokens: 0,
+			totalCost: 0
+		};
+		existing.inputTokens += data.inputTokens;
+		existing.outputTokens += data.outputTokens;
+		existing.cacheCreationTokens += data.cacheCreationTokens;
+		existing.cacheReadTokens += data.cacheReadTokens;
+		existing.totalCost += data.totalCost;
+		monthlyMap.set(month, existing);
+	}
+	const monthlyArray = Array.from(monthlyMap.values());
+	const sortOrder = options?.order || "desc";
+	const sortedMonthly = sort(monthlyArray);
+	return sortOrder === "desc" ? sortedMonthly.desc((item) => item.month) : sortedMonthly.asc((item) => item.month);
 }
 
 //#endregion
-export { DailyUsageSchema, SessionUsageSchema, UsageDataSchema, __commonJS, __require, __toESM, calculateCostForEntry, formatDate, getDefaultClaudePath, glob, loadSessionData, loadUsageData };
+export { DailyUsageSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, __commonJS, __require, __toESM, calculateCostForEntry, formatDate, getDefaultClaudePath, glob, loadDailyUsageData, loadMonthlyUsageData, loadSessionData };

package/dist/{data-loader-LMCrJ-lW.d.ts → data-loader-aUOjeZ06.d.ts}

@@ -1,6 +1,6 @@
-import { ArraySchema, InferOutput, NumberSchema, ObjectSchema, OptionalSchema, StringSchema } from "./index-BurjgCfW.js";
+import { ArraySchema, InferOutput, NumberSchema, ObjectSchema, OptionalSchema, RegexAction, SchemaWithPipe, StringSchema } from "./index-BurjgCfW.js";
 import { ModelPricing } from "./pricing-fetcher-DygIroMj.js";
-import { CostMode } from "./types-B3ib19os.js";
+import { CostMode, SortOrder } from "./types-y1JQzaKZ.js";
 
 //#region src/data-loader.d.ts
 declare const getDefaultClaudePath: () => string;
@@ -20,7 +20,7 @@ declare const UsageDataSchema: ObjectSchema<{
 }, undefined>;
 type UsageData = InferOutput<typeof UsageDataSchema>;
 declare const DailyUsageSchema: ObjectSchema<{
-  readonly date: StringSchema<undefined>;
+  readonly date: SchemaWithPipe<readonly [StringSchema<undefined>, RegexAction<string, undefined>]>;
   readonly inputTokens: NumberSchema<undefined>;
   readonly outputTokens: NumberSchema<undefined>;
   readonly cacheCreationTokens: NumberSchema<undefined>;
@@ -40,6 +40,15 @@ declare const SessionUsageSchema: ObjectSchema<{
   readonly versions: ArraySchema<StringSchema<undefined>, undefined>;
 }, undefined>;
 type SessionUsage = InferOutput<typeof SessionUsageSchema>;
+declare const MonthlyUsageSchema: ObjectSchema<{
+  readonly month: SchemaWithPipe<readonly [StringSchema<undefined>, RegexAction<string, undefined>]>;
+  readonly inputTokens: NumberSchema<undefined>;
+  readonly outputTokens: NumberSchema<undefined>;
+  readonly cacheCreationTokens: NumberSchema<undefined>;
+  readonly cacheReadTokens: NumberSchema<undefined>;
+  readonly totalCost: NumberSchema<undefined>;
+}, undefined>;
+type MonthlyUsage = InferOutput<typeof MonthlyUsageSchema>;
 declare const formatDate: (dateStr: string) => string;
 declare const calculateCostForEntry: (data: UsageData, mode: CostMode, modelPricing: Record<string, ModelPricing>) => number;
 interface DateFilter {
@@ -49,8 +58,10 @@ interface DateFilter {
 interface LoadOptions extends DateFilter {
   claudePath?: string;
   mode?: CostMode;
+  order?: SortOrder;
 }
-declare function loadUsageData(options?: LoadOptions): Promise<DailyUsage[]>;
+declare function loadDailyUsageData(options?: LoadOptions): Promise<DailyUsage[]>;
 declare function loadSessionData(options?: LoadOptions): Promise<SessionUsage[]>;
+declare function loadMonthlyUsageData(options?: LoadOptions): Promise<MonthlyUsage[]>;
 //#endregion
-export { DailyUsage, DailyUsageSchema as DailyUsageSchema$1, DateFilter, LoadOptions, SessionUsage, SessionUsageSchema as SessionUsageSchema$1, UsageData, UsageDataSchema as UsageDataSchema$1, calculateCostForEntry as calculateCostForEntry$1, formatDate as formatDate$1, getDefaultClaudePath as getDefaultClaudePath$1, loadSessionData as loadSessionData$1, loadUsageData as loadUsageData$1 };
+export { DailyUsage, DailyUsageSchema as DailyUsageSchema$1, DateFilter, LoadOptions, MonthlyUsage, MonthlyUsageSchema as MonthlyUsageSchema$1, SessionUsage, SessionUsageSchema as SessionUsageSchema$1, UsageData, UsageDataSchema as UsageDataSchema$1, calculateCostForEntry as calculateCostForEntry$1, formatDate as formatDate$1, getDefaultClaudePath as getDefaultClaudePath$1, loadDailyUsageData as loadDailyUsageData$1, loadMonthlyUsageData as loadMonthlyUsageData$1, loadSessionData as loadSessionData$1 };

package/dist/data-loader.d.ts

@@ -1,5 +1,5 @@
 import "./index-BurjgCfW.js";
 import "./pricing-fetcher-DygIroMj.js";
-import "./types-B3ib19os.js";
-import { DailyUsage, DailyUsageSchema$1 as DailyUsageSchema, DateFilter, LoadOptions, SessionUsage, SessionUsageSchema$1 as SessionUsageSchema, UsageData, UsageDataSchema$1 as UsageDataSchema, calculateCostForEntry$1 as calculateCostForEntry, formatDate$1 as formatDate, getDefaultClaudePath$1 as getDefaultClaudePath, loadSessionData$1 as loadSessionData, loadUsageData$1 as loadUsageData } from "./data-loader-LMCrJ-lW.js";
-export { DailyUsage, DailyUsageSchema, DateFilter, LoadOptions, SessionUsage, SessionUsageSchema, UsageData, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadSessionData, loadUsageData };
+import "./types-y1JQzaKZ.js";
+import { DailyUsage, DailyUsageSchema$1 as DailyUsageSchema, DateFilter, LoadOptions, MonthlyUsage, MonthlyUsageSchema$1 as MonthlyUsageSchema, SessionUsage, SessionUsageSchema$1 as SessionUsageSchema, UsageData, UsageDataSchema$1 as UsageDataSchema, calculateCostForEntry$1 as calculateCostForEntry, formatDate$1 as formatDate, getDefaultClaudePath$1 as getDefaultClaudePath, loadDailyUsageData$1 as loadDailyUsageData, loadMonthlyUsageData$1 as loadMonthlyUsageData, loadSessionData$1 as loadSessionData } from "./data-loader-aUOjeZ06.js";
+export { DailyUsage, DailyUsageSchema, DateFilter, LoadOptions, MonthlyUsage, MonthlyUsageSchema, SessionUsage, SessionUsageSchema, UsageData, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadDailyUsageData, loadMonthlyUsageData, loadSessionData };

package/dist/data-loader.js

@@ -1,6 +1,6 @@
-import { DailyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadSessionData, loadUsageData } from "./data-loader-r5ZcMQy7.js";
+import { DailyUsageSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadDailyUsageData, loadMonthlyUsageData, loadSessionData } from "./data-loader-CDv0IYZx.js";
 import "./dist-FwNhpFrW.js";
-import "./logger-Cu4Ir1a5.js";
-import "./pricing-fetcher-B5yPtoTB.js";
+import "./logger-DhDyJEC5.js";
+import "./pricing-fetcher-BCv1Vods.js";
 
-export { DailyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadSessionData, loadUsageData };
+export { DailyUsageSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, formatDate, getDefaultClaudePath, loadDailyUsageData, loadMonthlyUsageData, loadSessionData };

package/dist/{debug-BVxGf4UL.js → debug-Dk36WQTw.js}

@@ -1,7 +1,7 @@
-import { UsageDataSchema, glob } from "./data-loader-r5ZcMQy7.js";
+import { UsageDataSchema, glob } from "./data-loader-CDv0IYZx.js";
 import { safeParse } from "./dist-FwNhpFrW.js";
-import { logger } from "./logger-Cu4Ir1a5.js";
-import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-B5yPtoTB.js";
+import { logger } from "./logger-DhDyJEC5.js";
+import { calculateCostFromTokens, fetchModelPricing, getModelPricing } from "./pricing-fetcher-BCv1Vods.js";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";

package/dist/debug.js

@@ -1,7 +1,7 @@
-import "./data-loader-r5ZcMQy7.js";
+import "./data-loader-CDv0IYZx.js";
 import "./dist-FwNhpFrW.js";
-import "./logger-Cu4Ir1a5.js";
-import "./pricing-fetcher-B5yPtoTB.js";
-import { detectMismatches, printMismatchReport } from "./debug-BVxGf4UL.js";
+import "./logger-DhDyJEC5.js";
+import "./pricing-fetcher-BCv1Vods.js";
+import { detectMismatches, printMismatchReport } from "./debug-Dk36WQTw.js";
 
 export { detectMismatches, printMismatchReport };

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-import { __commonJS, __require, __toESM, loadSessionData, loadUsageData } from "./data-loader-r5ZcMQy7.js";
+import { __commonJS, __require, __toESM, loadDailyUsageData, loadMonthlyUsageData, loadSessionData } from "./data-loader-CDv0IYZx.js";
 import { calculateTotals, createTotalsObject, getTotalTokens } from "./calculate-cost-2IwHSzmi.js";
 import "./dist-FwNhpFrW.js";
-import { description, log, logger, name, version } from "./logger-Cu4Ir1a5.js";
-import "./pricing-fetcher-B5yPtoTB.js";
-import { detectMismatches, printMismatchReport } from "./debug-BVxGf4UL.js";
-import "./types-DFrbJmnT.js";
-import { sharedArgs, sharedCommandConfig } from "./shared-args-DN3jRldX.js";
+import { description, log, logger, name, version } from "./logger-DhDyJEC5.js";
+import "./pricing-fetcher-BCv1Vods.js";
+import { detectMismatches, printMismatchReport } from "./debug-Dk36WQTw.js";
+import "./types-BcXIBMQk.js";
+import { sharedArgs, sharedCommandConfig } from "./shared-args-BtMSktLn.js";
 import { formatCurrency, formatNumber } from "./utils-C7kg8MXN.js";
 import "./types-CFnCBr2I.js";
-import { createMcpServer } from "./mcp-DAzj5Pua.js";
+import { createMcpServer } from "./mcp-G-TIOcuj.js";
 import "./index-CISmcbXk-BotItq1T.js";
 import process$1 from "node:process";
 
@@ -2729,7 +2729,7 @@ var require_table = __commonJS({ "node_modules/cli-table3/src/table.js"(exports,
 	const debug = require_debug$1();
 	const utils = require_utils$1();
 	const tableLayout = require_layout_manager();
-	var Table$2 = class extends Array {
+	var Table$3 = class extends Array {
 		constructor(opts) {
 			super();
 			const options = utils.mergeOptions(opts);
@@ -2792,7 +2792,7 @@ var require_table = __commonJS({ "node_modules/cli-table3/src/table.js"(exports,
 			return str[0].length;
 		}
 	};
-	Table$2.reset = () => debug.reset();
+	Table$3.reset = () => debug.reset();
 	function doDraw(row, lineNum, result) {
 		let line = [];
 		row.forEach(function(cell) {
@@ -2801,7 +2801,7 @@ var require_table = __commonJS({ "node_modules/cli-table3/src/table.js"(exports,
 		let str = line.join("");
 		if (str.length) result.push(str);
 	}
-	module.exports = Table$2;
+	module.exports = Table$3;
 } });
 
 //#endregion
@@ -2881,21 +2881,21 @@ var require_picocolors = __commonJS({ "node_modules/picocolors/picocolors.js"(ex
 
 //#endregion
 //#region src/commands/daily.ts
-var import_cli_table3$1 = __toESM(require_cli_table3(), 1);
-var import_picocolors$1 = __toESM(require_picocolors(), 1);
+var import_cli_table3$2 = __toESM(require_cli_table3(), 1);
+var import_picocolors$2 = __toESM(require_picocolors(), 1);
 const dailyCommand = define({
 	name: "daily",
 	description: "Show usage report grouped by date",
 	...sharedCommandConfig,
 	async run(ctx) {
 		if (ctx.values.json) logger.level = 0;
-		const options = {
+		const dailyData = await loadDailyUsageData({
 			since: ctx.values.since,
 			until: ctx.values.until,
 			claudePath: ctx.values.path,
-			mode: ctx.values.mode
-		};
-		const dailyData = await loadUsageData(options);
+			mode: ctx.values.mode,
+			order: ctx.values.order
+		});
 		if (dailyData.length === 0) {
 			if (ctx.values.json) log(JSON.stringify([]));
 			else logger.warn("No Claude usage data found.");
@@ -2922,7 +2922,7 @@ const dailyCommand = define({
 			log(JSON.stringify(jsonOutput, null, 2));
 		} else {
 			logger.box("Claude Code Token Usage Report - Daily");
-			const table = new import_cli_table3$1.default({
+			const table = new import_cli_table3$2.default({
 				head: [
 					"Date",
 					"Input",
@@ -2962,13 +2962,13 @@ const dailyCommand = define({
 				"─".repeat(10)
 			]);
 			table.push([
-				import_picocolors$1.default.yellow("Total"),
-				import_picocolors$1.default.yellow(formatNumber(totals.inputTokens)),
-				import_picocolors$1.default.yellow(formatNumber(totals.outputTokens)),
-				import_picocolors$1.default.yellow(formatNumber(totals.cacheCreationTokens)),
-				import_picocolors$1.default.yellow(formatNumber(totals.cacheReadTokens)),
-				import_picocolors$1.default.yellow(formatNumber(getTotalTokens(totals))),
-				import_picocolors$1.default.yellow(formatCurrency(totals.totalCost))
+				import_picocolors$2.default.yellow("Total"),
+				import_picocolors$2.default.yellow(formatNumber(totals.inputTokens)),
+				import_picocolors$2.default.yellow(formatNumber(totals.outputTokens)),
+				import_picocolors$2.default.yellow(formatNumber(totals.cacheCreationTokens)),
+				import_picocolors$2.default.yellow(formatNumber(totals.cacheReadTokens)),
+				import_picocolors$2.default.yellow(formatNumber(getTotalTokens(totals))),
+				import_picocolors$2.default.yellow(formatCurrency(totals.totalCost))
 			]);
 			log(table.toString());
 		}
@@ -3010,6 +3010,114 @@ const mcpCommand = define({
 	}
 });
 
+//#endregion
+//#region src/commands/monthly.ts
+var import_cli_table3$1 = __toESM(require_cli_table3(), 1);
+var import_picocolors$1 = __toESM(require_picocolors(), 1);
+const monthlyCommand = define({
+	name: "monthly",
+	description: "Show usage report grouped by month",
+	...sharedCommandConfig,
+	async run(ctx) {
+		if (ctx.values.json) logger.level = 0;
+		const monthlyData = await loadMonthlyUsageData({
+			since: ctx.values.since,
+			until: ctx.values.until,
+			claudePath: ctx.values.path,
+			mode: ctx.values.mode,
+			order: ctx.values.order
+		});
+		if (monthlyData.length === 0) {
+			if (ctx.values.json) {
+				const emptyOutput = {
+					monthly: [],
+					totals: {
+						inputTokens: 0,
+						outputTokens: 0,
+						cacheCreationTokens: 0,
+						cacheReadTokens: 0,
+						totalTokens: 0,
+						totalCost: 0
+					}
+				};
+				log(JSON.stringify(emptyOutput, null, 2));
+			} else logger.warn("No Claude usage data found.");
+			process$1.exit(0);
+		}
+		const totals = calculateTotals(monthlyData);
+		if (ctx.values.debug && !ctx.values.json) {
+			const mismatchStats = await detectMismatches(ctx.values.path);
+			printMismatchReport(mismatchStats, ctx.values.debugSamples);
+		}
+		if (ctx.values.json) {
+			const jsonOutput = {
+				monthly: monthlyData.map((data) => ({
+					month: data.month,
+					inputTokens: data.inputTokens,
+					outputTokens: data.outputTokens,
+					cacheCreationTokens: data.cacheCreationTokens,
+					cacheReadTokens: data.cacheReadTokens,
+					totalTokens: getTotalTokens(data),
+					totalCost: data.totalCost
+				})),
+				totals: createTotalsObject(totals)
+			};
+			log(JSON.stringify(jsonOutput, null, 2));
+		} else {
+			logger.box("Claude Code Token Usage Report - Monthly");
+			const table = new import_cli_table3$1.default({
+				head: [
+					"Month",
+					"Input",
+					"Output",
+					"Cache Create",
+					"Cache Read",
+					"Total Tokens",
+					"Cost (USD)"
+				],
+				style: { head: ["cyan"] },
+				colAligns: [
+					"left",
+					"right",
+					"right",
+					"right",
+					"right",
+					"right",
+					"right"
+				]
+			});
+			for (const data of monthlyData) table.push([
+				data.month,
+				formatNumber(data.inputTokens),
+				formatNumber(data.outputTokens),
+				formatNumber(data.cacheCreationTokens),
+				formatNumber(data.cacheReadTokens),
+				formatNumber(getTotalTokens(data)),
+				formatCurrency(data.totalCost)
+			]);
+			table.push([
+				"─".repeat(12),
+				"─".repeat(12),
+				"─".repeat(12),
+				"─".repeat(12),
+				"─".repeat(12),
+				"─".repeat(12),
+				"─".repeat(10)
+			]);
+			table.push([
+				import_picocolors$1.default.yellow("Total"),
+				import_picocolors$1.default.yellow(formatNumber(totals.inputTokens)),
+				import_picocolors$1.default.yellow(formatNumber(totals.outputTokens)),
+				import_picocolors$1.default.yellow(formatNumber(totals.cacheCreationTokens)),
+				import_picocolors$1.default.yellow(formatNumber(totals.cacheReadTokens)),
+				import_picocolors$1.default.yellow(formatNumber(getTotalTokens(totals))),
+				import_picocolors$1.default.yellow(formatCurrency(totals.totalCost))
+			]);
+			log(table.toString());
+		}
+	}
+});
+
 //#endregion
 //#region src/commands/session.ts
 var import_cli_table3 = __toESM(require_cli_table3(), 1);
@@ -3020,13 +3128,13 @@ const sessionCommand = define({
 	...sharedCommandConfig,
 	async run(ctx) {
 		if (ctx.values.json) logger.level = 0;
-		const options = {
+		const sessionData = await loadSessionData({
 			since: ctx.values.since,
 			until: ctx.values.until,
 			claudePath: ctx.values.path,
-			mode: ctx.values.mode
-		};
-		const sessionData = await loadSessionData(options);
+			mode: ctx.values.mode,
+			order: ctx.values.order
+		});
 		if (sessionData.length === 0) {
 			if (ctx.values.json) log(JSON.stringify([]));
 			else logger.warn("No Claude usage data found.");
@@ -3130,6 +3238,7 @@ const sessionCommand = define({
 //#region src/commands/index.ts
 const subCommands = new Map();
 subCommands.set("daily", dailyCommand);
+subCommands.set("monthly", monthlyCommand);
 subCommands.set("session", sessionCommand);
 subCommands.set("mcp", mcpCommand);
 const mainCommand = dailyCommand;

package/dist/{logger-Cu4Ir1a5.js → logger-DhDyJEC5.js}

@@ -965,7 +965,7 @@ const consola = createConsola();
 //#endregion
 //#region package.json
 var name = "ccusage";
-var version = "0.5.0";
+var version = "0.6.0";
 var description = "Usage analysis tool for Claude Code";
 
 //#endregion

package/dist/logger.js

@@ -1,3 +1,3 @@
-import { log, logger } from "./logger-Cu4Ir1a5.js";
+import { log, logger } from "./logger-DhDyJEC5.js";
 
 export { log, logger };

package/dist/{mcp-DAzj5Pua.js → mcp-G-TIOcuj.js}

@@ -1,7 +1,7 @@
-import { __commonJS, __require, __toESM, getDefaultClaudePath, loadSessionData, loadUsageData } from "./data-loader-r5ZcMQy7.js";
+import { __commonJS, __require, __toESM, getDefaultClaudePath, loadDailyUsageData, loadSessionData } from "./data-loader-CDv0IYZx.js";
 import { description$1 as description, literal, object, optional, pipe, union } from "./dist-FwNhpFrW.js";
-import { name, version } from "./logger-Cu4Ir1a5.js";
-import { CostModes, dateSchema } from "./types-DFrbJmnT.js";
+import { name, version } from "./logger-DhDyJEC5.js";
+import { CostModes, dateSchema } from "./types-BcXIBMQk.js";
 import { anyType, arrayType, booleanType, discriminatedUnionType, enumType, literalType, numberType, objectType, optionalType, recordType, stringType, unionType, unknownType } from "./types-CFnCBr2I.js";
 import { toJsonSchema } from "./index-CISmcbXk-BotItq1T.js";
 import process$1 from "node:process";
@@ -37554,7 +37554,7 @@ function createMcpServer({ claudePath } = defaultOptions) {
 		description: "Show usage report grouped by date",
 		parameters: parametersSchema,
 		execute: async (args) => {
-			const dailyData = await loadUsageData({
+			const dailyData = await loadDailyUsageData({
 				...args,
 				claudePath
 			});

package/dist/mcp.d.ts

@@ -1,7 +1,7 @@
 import "./index-BurjgCfW.js";
 import "./pricing-fetcher-DygIroMj.js";
-import "./types-B3ib19os.js";
-import { LoadOptions } from "./data-loader-LMCrJ-lW.js";
+import "./types-y1JQzaKZ.js";
+import { LoadOptions } from "./data-loader-aUOjeZ06.js";
 import { FastMCP } from "fastmcp";
 
 //#region src/mcp.d.ts

package/dist/mcp.js

@@ -1,10 +1,10 @@
-import "./data-loader-r5ZcMQy7.js";
+import "./data-loader-CDv0IYZx.js";
 import "./dist-FwNhpFrW.js";
-import "./logger-Cu4Ir1a5.js";
-import "./pricing-fetcher-B5yPtoTB.js";
-import "./types-DFrbJmnT.js";
+import "./logger-DhDyJEC5.js";
+import "./pricing-fetcher-BCv1Vods.js";
+import "./types-BcXIBMQk.js";
 import "./types-CFnCBr2I.js";
-import { createMcpServer } from "./mcp-DAzj5Pua.js";
+import { createMcpServer } from "./mcp-G-TIOcuj.js";
 import "./index-CISmcbXk-BotItq1T.js";
 
 export { createMcpServer };

package/dist/{pricing-fetcher-B5yPtoTB.js → pricing-fetcher-BCv1Vods.js}

@@ -1,5 +1,5 @@
 import { number, object, optional, parse } from "./dist-FwNhpFrW.js";
-import { logger } from "./logger-Cu4Ir1a5.js";
+import { logger } from "./logger-DhDyJEC5.js";
 
 //#region src/pricing-fetcher.ts
 const ModelPricingSchema = object({

package/dist/pricing-fetcher.js

@@ -1,5 +1,5 @@
 import "./dist-FwNhpFrW.js";
-import "./logger-Cu4Ir1a5.js";
-import { calculateCostFromTokens, clearPricingCache, fetchModelPricing, getModelPricing } from "./pricing-fetcher-B5yPtoTB.js";
+import "./logger-DhDyJEC5.js";
+import { calculateCostFromTokens, clearPricingCache, fetchModelPricing, getModelPricing } from "./pricing-fetcher-BCv1Vods.js";
 
 export { calculateCostFromTokens, clearPricingCache, fetchModelPricing, getModelPricing };

package/dist/{shared-args-DN3jRldX.js → shared-args-BtMSktLn.js}

@@ -1,6 +1,6 @@
-import { getDefaultClaudePath } from "./data-loader-r5ZcMQy7.js";
+import { getDefaultClaudePath } from "./data-loader-CDv0IYZx.js";
 import { safeParse } from "./dist-FwNhpFrW.js";
-import { CostModes, dateSchema } from "./types-DFrbJmnT.js";
+import { CostModes, SortOrders, dateSchema } from "./types-BcXIBMQk.js";
 
 //#region src/shared-args.ts
 const parseDateArg = (value) => {
@@ -50,6 +50,13 @@ const sharedArgs = {
 		type: "number",
 		description: "Number of sample discrepancies to show in debug output (default: 5)",
 		default: 5
+	},
+	order: {
+		type: "enum",
+		short: "o",
+		description: "Sort order: desc (newest first) or asc (oldest first)",
+		default: "asc",
+		choices: SortOrders
 	}
 };
 const sharedCommandConfig = {

package/dist/shared-args.d.ts

@@ -42,6 +42,13 @@ declare const sharedArgs: {
     readonly description: "Number of sample discrepancies to show in debug output (default: 5)";
     readonly default: 5;
   };
+  readonly order: {
+    readonly type: "enum";
+    readonly short: "o";
+    readonly description: "Sort order: desc (newest first) or asc (oldest first)";
+    readonly default: "asc";
+    readonly choices: readonly ["desc", "asc"];
+  };
 };
 declare const sharedCommandConfig: {
   readonly args: {
@@ -87,6 +94,13 @@ declare const sharedCommandConfig: {
       readonly description: "Number of sample discrepancies to show in debug output (default: 5)";
       readonly default: 5;
     };
+    readonly order: {
+      readonly type: "enum";
+      readonly short: "o";
+      readonly description: "Sort order: desc (newest first) or asc (oldest first)";
+      readonly default: "asc";
+      readonly choices: readonly ["desc", "asc"];
+    };
   };
   readonly toKebab: true;
 };

package/dist/shared-args.js

@@ -1,8 +1,8 @@
-import "./data-loader-r5ZcMQy7.js";
+import "./data-loader-CDv0IYZx.js";
 import "./dist-FwNhpFrW.js";
-import "./logger-Cu4Ir1a5.js";
-import "./pricing-fetcher-B5yPtoTB.js";
-import "./types-DFrbJmnT.js";
-import { sharedArgs, sharedCommandConfig } from "./shared-args-DN3jRldX.js";
+import "./logger-DhDyJEC5.js";
+import "./pricing-fetcher-BCv1Vods.js";
+import "./types-BcXIBMQk.js";
+import { sharedArgs, sharedCommandConfig } from "./shared-args-BtMSktLn.js";
 
 export { sharedArgs, sharedCommandConfig };

package/dist/{types-DFrbJmnT.js → types-BcXIBMQk.js}

@@ -36,6 +36,7 @@ const CostModes = [
 	"calculate",
 	"display"
 ];
+const SortOrders = ["desc", "asc"];
 
 //#endregion
-export { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, dateSchema };
+export { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, SortOrders, dateSchema };

package/dist/{types-B3ib19os.d.ts → types-y1JQzaKZ.d.ts}

@@ -75,5 +75,7 @@ interface TokenData {
 }
 declare const CostModes: readonly ["auto", "calculate", "display"];
 type CostMode = (typeof CostModes)[number];
+declare const SortOrders: readonly ["desc", "asc"];
+type SortOrder = (typeof SortOrders)[number];
 //#endregion
-export { CostMode, CostModes as CostModes$1, LiteLLMModelPrices, LiteLLMModelPricesSchema as LiteLLMModelPricesSchema$1, ModelSpec, ModelSpecSchema as ModelSpecSchema$1, TokenData, TokenTotals, dateSchema as dateSchema$1 };
+export { CostMode, CostModes as CostModes$1, LiteLLMModelPrices, LiteLLMModelPricesSchema as LiteLLMModelPricesSchema$1, ModelSpec, ModelSpecSchema as ModelSpecSchema$1, SortOrder, SortOrders as SortOrders$1, TokenData, TokenTotals, dateSchema as dateSchema$1 };

package/dist/types.d.ts

@@ -1,3 +1,3 @@
 import "./index-BurjgCfW.js";
-import { CostMode, CostModes$1 as CostModes, LiteLLMModelPrices, LiteLLMModelPricesSchema$1 as LiteLLMModelPricesSchema, ModelSpec, ModelSpecSchema$1 as ModelSpecSchema, TokenData, TokenTotals, dateSchema$1 as dateSchema } from "./types-B3ib19os.js";
-export { CostMode, CostModes, LiteLLMModelPrices, LiteLLMModelPricesSchema, ModelSpec, ModelSpecSchema, TokenData, TokenTotals, dateSchema };
+import { CostMode, CostModes$1 as CostModes, LiteLLMModelPrices, LiteLLMModelPricesSchema$1 as LiteLLMModelPricesSchema, ModelSpec, ModelSpecSchema$1 as ModelSpecSchema, SortOrder, SortOrders$1 as SortOrders, TokenData, TokenTotals, dateSchema$1 as dateSchema } from "./types-y1JQzaKZ.js";
+export { CostMode, CostModes, LiteLLMModelPrices, LiteLLMModelPricesSchema, ModelSpec, ModelSpecSchema, SortOrder, SortOrders, TokenData, TokenTotals, dateSchema };

package/dist/types.js

@@ -1,4 +1,4 @@
 import "./dist-FwNhpFrW.js";
-import { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, dateSchema } from "./types-DFrbJmnT.js";
+import { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, SortOrders, dateSchema } from "./types-BcXIBMQk.js";
 
-export { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, dateSchema };
+export { CostModes, LiteLLMModelPricesSchema, ModelSpecSchema, SortOrders, dateSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccusage",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Usage analysis tool for Claude Code",
   "homepage": "https://github.com/ryoppippi/ccusage#readme",
   "bugs": {