feat: add `--last` to report the most recent N periods by ryoppippi · Pull Request #1498 · ccusage/ccusage

ryoppippi · 2026-07-27T13:02:34Z

What do you want to change?

Add a --last <N> option to the reports that group rows by a calendar period, counting in whatever unit the report already uses:

ccusage daily --last 1     # today
ccusage weekly --last 1    # this week
ccusage monthly --last 1   # this month
ccusage codex daily --last 7   # the last seven days of Codex usage

Why?

Checking today's or this week's usage currently means working out the dates yourself and passing --since. This keeps the command surface as it is — no new subcommands — and maps one option onto the day/week/month granularity each report already has, which is the shape suggested in #1300 and preferred over the today / this-week commands proposed in #1321.

How?

ccusage-core gains last_periods_since, which turns a unit plus a count into the compact YYYYMMDD --since bound the loaders already understand. It takes "today" as an argument so it stays deterministic in tests, and reuses week_start so the window lines up with the report's own weekly bucketing.
The parser records only the count, since the unit it counts depends on the command. The binary resolves it into --since right after parsing, using the report timezone for "today" and the command's own week start (Monday everywhere except ccusage claude weekly, which honors -w). Nothing downstream changes.
--last is rejected on session, blocks, and statusline, which have no calendar period, and alongside --since, --until, or --sections, where the intended window would be ambiguous.
No short alias: -l used to be --locale until 8792ff5 removed that option, so --last deliberately leaves it unclaimed and a test records that.

Covered by unit tests for the date math, the parse and rejection paths, and the resolution of each command shape, plus a manual check against a dated fixture (daily --last 1 → today only, weekly --last 2 → the current and previous week, monthly --last 2 → this month and last).

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

Summary by cubic

Add --last <N> to daily/weekly/monthly reports to show only the most recent N periods, auto-resolved to --since. Works on unified and per‑agent reports to make “today/this week/this month” easy.

New Features
- Supports daily, weekly, and monthly for unified and per‑agent commands; bare ccusage --last N applies to daily.
- Converts --last N to compact YYYYMMDD --since using the report timezone; weekly windows align to the report’s week start (Monday by default; ccusage claude weekly respects -w).
- Rejected on session, blocks, and statusline, and when combined with --since, --until, or --sections; N must be a positive integer.
- Added last_periods_since in ccusage-core, resolution logic in the ccusage CLI, and updated ccusage-cli parser/help; guides and README document “Recent Periods” with examples; tests cover parsing, date math, and rejection paths.
Refactors
- Dropped the -l short alias (formerly --locale); --last has no short form, and a test locks in that -l remains unused.

^{Written for commit 834e1d3. Summary will update on new commits.}

Summary by CodeRabbit

New Features
- Added a --last <N> option for daily, weekly, and monthly reports.
- Supports viewing the current period or multiple recent periods, including custom week boundaries.
- Added validation for unsupported commands, conflicting date filters, and invalid values.
Documentation
- Updated CLI, daily, weekly, monthly, and general usage guides with examples and option details.

Reports that group rows by day, week, or month all filter through the same compact YYYYMMDD `--since` bound, so a shortcut for "the most recent N periods" only needs to resolve that bound. `last_periods_since` takes the report's calendar unit, the count, the current date already resolved in the report timezone, and the week start the report buckets with. Passing the date in keeps the helper deterministic in tests, and reusing `week_start` keeps the window aligned with the weekly bucketing itself instead of duplicating the weekday math. Co-authored-by: ryoppippi <[email protected]>

Checking today's or this week's usage meant working out the dates and passing `--since` by hand. `-l, --last N` now names the window in the unit the report already groups by: `ccusage daily --last 1` is today, `ccusage weekly --last 1` is the current week, and `ccusage monthly --last 1` is this month. It works the same way on the per-agent reports, so `ccusage codex daily --last 7` covers the last seven days. The parser only records the count, because the calendar unit it counts depends on the command; the binary resolves it into `--since` once the command is known, using the report timezone for "today" and the command's own week start. Every loader already honors `--since`, so nothing downstream changes. `--last` is rejected on the session, blocks, and statusline reports, which have no calendar period, and alongside `--since`, `--until`, or `--sections`, where the intended window would be ambiguous. Co-authored-by: ryoppippi <[email protected]>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

coderabbitai · 2026-07-27T13:02:42Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 58151383-7079-4423-b255-8292ad9e15ed

📥 Commits

Reviewing files that changed from the base of the PR and between d7fec09 and 834e1d3.

⛔ Files ignored due to path filters (1)

rust/crates/ccusage-cli-parser/src/snapshots/ccusage_cli_parser__tests__codex_daily_help.snap is excluded by !**/*.snap

📒 Files selected for processing (14)

apps/ccusage/README.md
docs/guide/cli-options.md
docs/guide/daily-reports.md
docs/guide/monthly-reports.md
docs/guide/weekly-reports.md
rust/crates/ccusage-cli-parser/src/cli-commands.json
rust/crates/ccusage-cli-parser/src/cli-help.json
rust/crates/ccusage-cli-parser/src/parser.rs
rust/crates/ccusage-cli-parser/src/tests.rs
rust/crates/ccusage-cli/src/types.rs
rust/crates/ccusage-core/src/last_window.rs
rust/crates/ccusage-core/src/lib.rs
rust/crates/ccusage/src/cli.rs
rust/crates/ccusage/src/cli/last_window.rs

📝 Walkthrough

Walkthrough

The CLI adds a validated --last N option for daily, weekly, and monthly reports. It computes calendar-aligned since dates, wires period-specific command options, adds parser and date-window tests, and documents usage and restrictions.

Changes

Recent periods filtering

Layer / File(s)	Summary
Parser contracts and command wiring `rust/crates/ccusage-cli-parser/src/cli-commands.json`, `rust/crates/ccusage-cli-parser/src/cli-help.json`, `rust/crates/ccusage-cli-parser/src/parser.rs`, `rust/crates/ccusage-cli-parser/src/tests.rs`, `rust/crates/ccusage-cli/src/types.rs`	Adds `--last` parsing, positive-integer validation, command restrictions, period-specific option presets, shared argument storage, and parser coverage.
Calendar window calculation `rust/crates/ccusage-core/src/last_window.rs`, `rust/crates/ccusage-core/src/lib.rs`	Adds day, week, and month period units and computes inclusive `YYYYMMDD` window starts with configurable week boundaries.
CLI window resolution `rust/crates/ccusage/src/cli.rs`, `rust/crates/ccusage/src/cli/last_window.rs`	Maps commands to calendar units, resolves `--last` into `since`, preserves weekly start settings, and centralizes usage errors.
Recent-period documentation `apps/ccusage/README.md`, `docs/guide/*.md`	Documents recent daily, weekly, and monthly periods, examples, inclusivity, week starts, and incompatible options.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Parser
  participant CLIResolver
  participant CoreWindow
  User->>Parser: provide --last N and report command
  Parser->>Parser: validate and store shared.last
  Parser-->>CLIResolver: return parsed Cli
  CLIResolver->>CoreWindow: calculate period start
  CoreWindow-->>CLIResolver: return since date
  CLIResolver-->>User: continue with resolved report window

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch cursor/add-last-n-report-window-option-98d7

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

cloudflare-workers-and-pages · 2026-07-27T13:03:31Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	ccusage-guide	`834e1d3`	Commit Preview URL Branch Preview URL	Jul 27 2026, 01:13 PM

Cover `--last` where readers look for date filtering: a general section in the CLI options guide with the rules that are easy to trip over (the count includes the current period, the week start follows the report, and it cannot be mixed with `--since`, `--until`, or `--sections`), and a short per-report section in the daily, weekly, and monthly guides that links back to it. The README gains the three shortcut examples next to the existing `--since`/`--until` example and a feature bullet, since that list is what people scan before reading the guides. Co-authored-by: ryoppippi <[email protected]>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

pkg-pr-new · 2026-07-27T13:08:47Z

Open in StackBlitz

ccusage

npx https://pkg.pr.new/ccusage@1498

@ccusage/ccusage-darwin-arm64

npx https://pkg.pr.new/@ccusage/ccusage-darwin-arm64@1498

@ccusage/ccusage-darwin-x64

npx https://pkg.pr.new/@ccusage/ccusage-darwin-x64@1498

@ccusage/ccusage-linux-arm64

npx https://pkg.pr.new/@ccusage/ccusage-linux-arm64@1498

@ccusage/ccusage-linux-x64

npx https://pkg.pr.new/@ccusage/ccusage-linux-x64@1498

@ccusage/ccusage-win32-x64

npx https://pkg.pr.new/@ccusage/ccusage-win32-x64@1498

commit: 834e1d3

`-l` was the short alias of `--locale` until 8792ff5 removed that option, so reusing it would silently rebind a flag people may still have in scripts and aliases. The long form is explicit enough on its own, and a test now records that `-l` stays unclaimed. Co-authored-by: ryoppippi <[email protected]>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

github-actions · 2026-07-27T13:14:35Z