Repository navigation
feat(usage): add structured usage analysis commands - #662
Conversation
16a0ce8 to
05357a2
Compare
There was a problem hiding this comment.
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.


Customers need structured usage data to compare periods and attribute increases without dashboard exports. Add
depot usagecommands 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 usagewith subcommandsseries,breakdown,report,current, andagentsthat call the newUsageAnalyticsServiceConnect client and print protobuf JSON (large integer counts stay as strings). Auth is organization API or read-only org tokens viaDEPOT_TOKENor--tokenonly—no implicit login/JIT credentials and no prompts.breakdownsupports 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.gowires the client; root registers the command; buf.builddepot/apigen modules are bumped.docs/usage-analysis.mddocuments 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.