docs(cli): document usage commands#1408
Conversation
Vendors the Usage API OpenAPI spec (GET /v1/usage/summary,
POST /v1/usage/time-series) into src/openapi/usage-api and wires it into the
Admin API nav section as "Usage API Endpoints", mirroring how the Admin API
("Apps API") endpoints are surfaced.
The spec is vendored locally for now because usage-api.alchemy.com is not yet
serving its /openapi.yaml publicly; once it is, this can switch to a
content/remote-specs.json entry (like admin-api) for auto-sync.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Usage API is path-routed (`/v1/usage*`) through the Apps API ALB at admin-api.alchemy.com (see terraform aws_alb_listener_rule.admin_api_usage), not served directly at usage-api.alchemy.com. Match the public host (and the sibling admin-api spec's server) so the reference shows the correct base URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per the sync-docs-as-code pattern, register the Usage API spec as a remote entry (served at https://admin-api.alchemy.com/v1/usage/openapi.json) and remove the vendored src/openapi/usage-api/ copy. content/docs.yml already references api-name: usage-api; the remote entry now supplies it. Blocked: merge only after the dashboard change serving the spec at that URL deploys (OMGWINNING/dashboard#8050) — CI lints the live URL. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a Usage (alpha) section to the Alchemy CLI reference covering `alchemy usage summary` and `alchemy usage timeseries`, including the time-series flag table for date ranges, granularity, filters, and group-by. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b02eb48a39
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | `alchemy usage summary` | Get an account usage summary | | ||
| | `alchemy usage timeseries` | Get account usage time-series data. Alias: `time-series`. | |
There was a problem hiding this comment.
For users who follow this page's npm i -g @alchemy/cli@latest install path, these commands appear to be unavailable: the public alchemyplatform/alchemy-cli command tree/release docs currently have no usage command (and no usage command file under src/commands), so alchemy usage summary and alchemy usage timeseries will fail unless the user has an unreleased/internal build. Please either gate this section on the CLI version that contains the command or hold it until that CLI release is public.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Thanks — the release-coordination concern is fair. The usage commands do exist in alchemy-cli, and they're being promoted from alpha to GA in alchemy-cli#96, but they aren't in a public @alchemy/cli@latest npm release yet, so a reader following the npm i -g @alchemy/cli@latest path today would hit "unknown command" for alchemy usage summary / alchemy usage timeseries.
The right sequencing is to hold the published version of this section (or gate it behind a "requires @alchemy/cli ≥ " note) until the alchemy-cli#96 GA release publishes, then drop the version caveat. Since the exact gating depends on the CLI release timing/version — a coordination + judgment call rather than a mechanical docs edit — and this repo's commit policy, I'm leaving this for @lohnim to land alongside the alchemy-cli#96 release rather than guessing a version here. Flagging it for manual follow-up; happy to draft the version-note wording once the GA version number is known.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4 participants
Summary
Adds a Usage section to the Alchemy CLI reference page (
content/tutorials/build-with-ai/alchemy-cli.mdx), documenting theusagecommand surface that was previously undocumented.The section is placed right after App (Admin API) since both authenticate via browser login, and covers:
alchemy usage summaryandalchemy usage timeseries(with thetime-seriesalias)timeseries: date/time range,--granularity,--products,--metrics, the four filters (--app-ids,--networks,--methods,--request-types), and--group-by, mirroring the command's actual options and validation rulesTest plan
alchemy usage timeseries --help🤖 Generated with Claude Code