Skip to content

feat(usage): add structured usage analysis commands - #662

Merged
ImLunaHey merged 5 commits into
mainfrom
luna/dep-7658-usage
Nov 17, 2026
Merged

ImLunaHey merged 5 commits into
mainfrom
luna/dep-7658-usage

Conversation

@ImLunaHey

@ImLunaHey ImLunaHey commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Customers need structured usage data to compare periods and attribute increases without dashboard exports. Add depot usage commands for daily series, paginated breakdowns, reports, agent usage, and current-period totals.

Uses the public contract implemented by https://github.com/depot/api/pull/6686. Organization and reader tokens determine the organization; personal login tokens are unsupported. JSON preserves large counts, and errors produce no partial usage output.

Rebased onto current main, preserving Luna’s original commits. Validation: full Go suite, usage race tests, golangci-lint, native build, module checks, and npm formatting/type checks pass. Production API/MCP deployment is confirmed by Polylane’s November 17 snapshot; successful authenticated usage reads remain unverified because the available CLI login is a personal token. Release this CLI before publishing depot/docs#192.

Refs DEP-7658. Updated with GPT-6 Astra in T3 Code through the Codex harness.


Note

Low Risk
Additive read-only CLI surface with explicit org-token auth; risk is mainly dependency on deployed UsageAnalyticsService and correct token scoping.

Overview
Adds depot usage with subcommands series, breakdown, report, current, and agents that call the new UsageAnalyticsService Connect client and print protobuf JSON (large integer counts stay as strings). Auth is organization API or read-only org tokens via DEPOT_TOKEN or --token only—no implicit login/JIT credentials and no prompts.

breakdown supports paginated attribution across products (container builds, GitHub Actions, Depot CI, test results) with validation for time windows (max 93 days), product/group pairings, and filter flags. pkg/api/usage.go wires the client; root registers the command; buf.build depot/api gen modules are bumped. docs/usage-analysis.md documents usage patterns, and tests cover round-trips, validation-before-network, and error paths that emit no partial JSON.

Reviewed by Cursor Bugbot for commit 17c9dfa. Bugbot is set up for automated code reviews on this repo. Configure here.

@linear-code

linear-code Bot commented Nov 4, 2026

Copy link
Copy Markdown

DEP-7658

@ImLunaHey
ImLunaHey marked this pull request as ready for review November 17, 2026 09:36

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Comment thread go.mod Resolved
Comment thread pkg/cmd/usage/usage.go Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: medium. Approved. Cursor Bugbot completed successfully with no findings requiring human review.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router and Approver

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the follow-up commit. It fixes both earlier points: examples/go.mod and examples/go.sum now pin the same buf.build depot/api version as the root module, and the token now comes only from --token or DEPOT_TOKEN, so the login-token fallback is gone. I found no new bugs. This adds a new user-facing command group that sends organization tokens to a new API, and the PR says authenticated reads haven't been checked against production yet, so a human look would still be worthwhile.

What was reviewed:

  • Validation in pkg/cmd/usage/usage.go: start/end parsing and the 93-day limit, page-size bounds, the supported product/group-by pairs, and the per-filter checks. The breakdown switch only reaches pairs that validate() already accepted.
  • The call[] helper sends every RPC through api.WithAuthentication, the same way other commands do. A failed request writes nothing to stdout.
Extended reasoning...

The change adds a 192-line depot usage command group, a usage analytics client constructor, the root command registration and tests, and bumps the buf.build depot/api modules in both go.mod files. The sensitive part is the auth token: it is read only from --token or DEPOT_TOKEN and sent as a bearer token through the existing WithAuthentication helper. Commit 17c9dfa fixes both earlier inline findings. I deferred because this is a new public CLI surface backed by a new API whose authenticated path is unverified, which is a product and API decision for a human rather than a mechanical change.

@ImLunaHey
ImLunaHey merged commit 002ee29 into main Nov 17, 2026
13 checks passed
@ImLunaHey
ImLunaHey deleted the luna/dep-7658-usage branch November 17, 2026 09:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant