███╗ ██╗███████╗ ██████╗ ███╗ ██╗
████╗ ██║██╔════╝██╔═══██╗████╗ ██║
██╔██╗ ██║█████╗ ██║ ██║██╔██╗ ██║
██║╚██╗██║██╔══╝ ██║ ██║██║╚██╗██║
██║ ╚████║███████╗╚██████╔╝██║ ╚████║
╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝ ╚═══╝
neon cli v0.0.1 · agent-friendly usage & metrics
Agent-friendly CLI for Neon. Answers the one question the dashboard won't: where is my money going, by project, right now?
neon usage --granularity hourly --last 1h◇ ✓ 43 projects · hourly
usage by project
window 2026-04-23 03:38 → 2026-04-23 04:38 UTC · hourly
PROJECT ID COMPUTE ROOT BR CHILD BR EGRESS
──────────────── ──────────────────────────── ───────── ─────── ──────── ──────
maca.sh red-firefly-70089523 0.25 CU·h 43.4 KB 0 B 173 KB
devphotos tiny-sky-12271004 0.00 CU·h 42.8 KB 0 B 0 B
cal.date icy-glade-88201525 0.00 CU·h 40.8 KB 0 B 0 B
claude.meme lingering-meadow-03519292 0.00 CU·h 50.5 KB 0 B 0 B
moraleja.design fancy-cake-56904804 0.00 CU·h 41.5 KB 572 B 0 B
croma-dev ancient-dream-53926171 0.00 CU·h 2.38 MB 0 B 0 B
…
TOTAL 0.25 CU·h 3.18 MB 1.02 KB 173 KB
next steps
→ neon usage --project <id> drill into one project with a per-bucket chart
→ neon usage --granularity hourly --last 24h zoom in on the last day
→ neon billing current-period running totals
A colored, sortable, per-project breakdown of compute hours, storage, written bytes, and egress — in the terminal, in ~200ms, with --json for agents.
Status:
0.0.1. Read-only commands (auth, projects, orgs, usage, billing, invoice). Writes (branches, endpoints, ops) are deliberately not here yet — see Roadmap.
The official neonctl is great for resource management (projects, branches, endpoints) but does not expose the consumption history endpoint. Every "where did my money go" question still routes through the web dashboard, which:
- only shows aggregates, not per-project series;
- doesn't let you sort or pivot;
- has no JSON export;
- is invisible to agents and CI.
This CLI fills exactly that gap. It hits the same console.neon.tech/api/v2/consumption_history/projects endpoint Neon uses for billing, so the numbers match your invoice — and there's a dedicated neon invoice command that proves it, down to the cent.
git clone <this-repo> neon-cli
cd neon-cli
bun install
bun run build
alias neon="node $(pwd)/packages/cli/dist/index.js"Or run straight from source with Bun:
bun run --filter @crafter/neon-cli dev <command>Get an API key at https://console.neon.tech/app/settings/api-keys, then either:
neon auth login # prompts for the key, stores it at ~/.neon/config.json (mode 0600)
# or
export NEON_API_KEY=napi_... # env var always winsneon auth status # where the key comes from (env / config / none)
neon auth whoami # who the key belongs to
neon auth logout # forget the saved key (env var untouched)neon usage # this month so far, daily, all projects
neon usage --last 7d # last 7 days
neon usage --last 24h --granularity hourly # last 24 hours, hourly buckets
neon usage --from 2026-04-01 --to 2026-04-15
neon usage --granularity monthly # year view
neon usage --org org_abc123 # scope to one org
neon usage --project shy-darkness-12345 # one project + per-bucket bar chart
neon usage --metrics compute_unit_seconds,public_network_transfer_bytes
neon usage --json | jq '.projects[] | {id: .project_id, cu_h: (.totals.compute_unit_seconds/3600)}'Default metrics: compute_unit_seconds, root_branch_bytes_month, child_branch_bytes_month, public_network_transfer_bytes. Pass --metrics to override.
Hits the v2 consumption endpoint (/consumption_history/v2/projects) — the one whose numbers match your invoice. Available v2 metrics:
| metric | meaning |
|---|---|
compute_unit_seconds |
billed compute, in CU·seconds (rendered as CU·hours) |
root_branch_bytes_month |
root-branch storage |
child_branch_bytes_month |
child-branch storage |
instant_restore_bytes_month |
point-in-time restore window |
public_network_transfer_bytes |
public egress |
private_network_transfer_bytes |
private egress |
extra_branches_month |
branch count above plan allowance |
Granularity limits (per Neon's API):
hourly— last 168 hoursdaily— last 60 daysmonthly— last year
Rebuilds a month's invoice from the consumption API using published plan rates and optionally diffs it against your actual invoice.
neon invoice # previous full month, Launch plan
neon invoice --month 2026-03 --plan launch
neon invoice --month 2026-03 --expected ./march-2026.json
neon invoice --month 2026-03 --expected-total 38.38
neon invoice --month 2026-03 --by-project # compute cost per project--expected <path> accepts a JSON file with any subset of the following keys (any _-prefixed fields are ignored so you can annotate your own file):
{
"_invoice_number": "PGFCAR-00007",
"_period": "Mar 1 – 31, 2026",
"compute_cu_hours": 355.625556,
"compute_amount": 37.70,
"root_storage_gb_month": 1.884952,
"root_storage_amount": 0.66,
"public_transfer_gb": 0.630344,
"public_transfer_amount": 0.00,
"total": 38.38
}When an expected file is passed, each line item is shown next to the invoice value with Δ USAGE and Δ $ columns (green for match, yellow for small diffs, red for overage).
neon projects # table sorted by most recently updated
neon projects --org org_abc123
neon projects --json | jq '.[].id'Prints region, PG version, created/updated, and the current billing-period running totals from GET /projects/{id} (transfer / written / storage·hour / compute time).
neon billing # all projects, sorted by data transfer
neon billing --sort storage # or by storage / written / nameSame numbers as the per-project endpoint, aggregated and sortable. Resets at the start of each billing period.
Lists organizations the current user belongs to.
--json— emit JSON to stdout (auto-on when piped). Errors and "next steps" go to stderr.-q, --quiet— suppress spinners and command echoes.--org <id>— default organization for the session (per-command--orgoverrides).-V, --version,-h, --help.
NO_COLOR=1 and a non-TTY stdout both disable colors automatically.
Every command emits a single JSON value to stdout when --json is set or stdout isn't a TTY. Non-essential output (spinners, next-step hints, errors) goes to stderr — pipe-friendly.
# total CU·hours used this month, across every project
neon usage --json \
| jq '[.projects[].totals.compute_unit_seconds] | add / 3600'
# this month's expected total, straight from the consumption API
neon invoice --json | jq '.expected_total_usd'packages/cli/
src/
index.ts # commander entry, registers all command groups
commands/
auth.ts # login / logout / status / whoami
projects.ts # list + show
orgs.ts # list
usage.ts # consumption history (the showcase)
billing.ts # current-period running totals
invoice.ts # month-end reconciliation against plan rates
lib/
api.ts # fetch wrapper, typed responses, NeonApiError
config.ts # ~/.neon/config.json + NEON_API_KEY env override
pricing.ts # plan rates (free / launch / scale / business)
output.ts # ANSI colors, emit(), reportError()
table.ts # ANSI-aware column padding
format.ts # bytes / CU·h / dates / ASCII bars
spinner.ts # @clack/prompts wrapper, NOOP under --json
banner.ts # ASCII banner
dates.ts # range parsing (--from/--to/--last)
- Runtime: Bun for dev, Node 20+ for the published bundle.
- Build: tsup → single ESM file with shebang, ~34 KB.
- Style: Biome (tabs, double quotes).
- HTTP: native
fetch, no SDK dependency.
neon branches list/create/delete/resetneon endpoints suspend/restartneon connection-string(script-friendly)neon set-context(default project/org)- Per-account consumption (
/consumption_history/account) - Watch mode for
usage(live updates while you work) - MCP server so agents can pull metrics without holding an API key
Unaffiliated with Neon. Uses the public REST API at console.neon.tech/api/v2. Endpoints, response shapes, metric names, and plan rates are subject to change — neon invoice hard-codes April 2026 pricing and should be verified against neon.com/pricing before you rely on it for accounting.