Skip to content

Add datumctl usage command, shipping alongside billing's new usage query API #266

Description

@mattdjenkinson

Summary

Add a datumctl usage (or datumctl billing usage) command that queries the new billable-usage endpoint being added to the billing service: GET /v1/billing-accounts/{billingAccountId}/usage. Returns normalized, FOCUS-aligned usage rows (meter/service identity, charge period, consumed quantity + unit, dimensions) as JSON, suitable for scripting.

Design doc: docs/enhancements/usage-query-api.md in milo-os/billing (PR #95).
Tracked by: milo-os/billing#94.

Motivation

Today there is no CLI path to usage/cost data at all — customers running cost automation have to go through the portal UI or ask staff to query the provider's console directly. The billing service is adding a provider-agnostic usage query API specifically so portals and the CLI can be normal authenticated callers instead of each needing provider-specific integration. datumctl usage is the first caller that depends on nothing but the public API (no session cookie, no portal BFF), making it the cleanest validation that the new endpoint's auth and response shape are genuinely self-serve-ready.

Scope

  • This command should ship in the same rollout wave as the billing usage-api endpoint, not as a deferred follow-up — it's the primary way this work gets exercised end-to-end before the portal migrations land.
  • Auth: use whatever service-account/API token flow datumctl already has for other Milo control-plane calls; no new credential type is expected.
  • Output: at minimum, a table view and a --output json mode; flags for --billing-account, --from, --to, --project, --meter mirroring the API's query parameters.

Non-Goals

  • Cost/pricing display — the API's cost fields are reserved/nullable until the billing service's pricing engine ships rates (Pricing via Amberflow milo-os/billing#73). Command should render quantity/unit correctly either way and simply omit cost when absent.
  • Any new auth/credential mechanism — reuse the existing one.

Open Questions

  • Where should this live in the existing command tree — top-level datumctl usage, or nested under an existing billing/billing-accounts command family if one exists?
  • What table/JSON output conventions does this repo already have for similar list-style commands, to match rather than invent a new shape?

Refs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions