Inspect AI usage on your machine.

Requires Node 22 or newer. The public npm registry reports v0.9.12, checked October 3, 2026. Use npx aibill@latest --version to check the version you run.

npx aibill@latest init
npx aibill@latest
npx aibill@latest doctor --sources

Init performs a real 30-day machine-wide Claude Code, Codex, and experimental Gemini CLI financial scan. The project where you run it owns the project-local .ai-spend-agent state directory; init preserves existing connector, audit, and spend state. The private status cache contains Claude Code and Codex aggregates—not prompts, responses, project names, transcript paths, session IDs, or credential references.

Gemini is fixture-verified and financial-only. It can contribute estimated API-equivalent value when supported chat evidence is complete; otherwise the evidence stays missing. Gemini never enters statusline, Glance, Context Health, Apply, plan, runway, or invocation evidence.

Use --plan <id> only when automatic plan detection cannot identify your subscription. A plan label does not prove remaining entitlement or billed cost.

The complete, version-matched list is always available from npx aibill --help.

npx aibill statusline install
npx aibill statusline refresh
npx aibill statusline uninstall

The optional line is installed only in Claude Code, but its cache can hold separately labeled Claude Code and Codex cohorts. Claude Code asks the runner to render about every 30 seconds; that re-reads the cache and does not rescan transcripts. Use statusline refresh or rerun init when you need fresh evidence.

• Metered mode leads with evidence-labeled dollars.
• Subscription mode leads with transcript-reported runway only; missing limits are not inferred.
• Mixed mode keeps subscribed runway and metered money separate.
• ~ means API-equivalent value. Untilded billed money requires verified provider evidence.
• Cache evidence becomes stale after five minutes and is labeled accordingly.

connect registers a local connector stub and prints the exact next command. It does not fetch billing data. Only sync-provider makes the read-only provider API request.

npx aibill connect openai
read -rsp "OpenAI Admin key: " OPENAI_ADMIN_KEY; printf "\n"
export OPENAI_ADMIN_KEY
npx aibill sync-provider   --provider openai   --auth-reference env:OPENAI_ADMIN_KEY   --start-time <unix-seconds>

OpenAI and Anthropic connectors have non-empty live verification. Cursor and GitHub Copilot connectors remain fixture-verified beta pending live-account QA. Final invoices can still include credits, discounts, taxes, or later adjustments.

npx aibill apply writes a prompt, action plan, policy draft, verification plan, and demo package under the project’s .ai-spend-agent/ directory. In local-transcript mode it freshly rereads the matching evidence. In connected-provider mode it uses receipt-bound state from the latest explicit sync and does not silently contact the provider. It changes no external system.

The prompt asks a coding agent to inspect the cited candidates, show exact changes and rollback, wait for explicit approval, and compare matched future sessions. Sample Apply is explicitly non-executable. Provider buckets or daily aggregates that cannot prove a call-level counterfactual remain reconciliation evidence, not invented savings advice.

The guided npx aibill improve command wraps this loop end to end: it records a named local self-attested approval before printing any agent handoff, reuses one command for the matched experiment, and later calculates the quality-gated before/after result. That percentage belongs to your own matched sessions — it is never a universal saving, provider-bill, or ROI claim.

The local CLI and hosted Workspace are separate data flows. Invited members can pair a machine from Workspace Settings → Machines, review the sharing scope and explicitly approve an upload. See the Workspace activity guide before connecting.

npx aibill@latest workspace connect
npx aibill@latest workspace status
npx aibill@latest workspace push
npx aibill@latest workspace disconnect

Run each command when needed; these are separate actions. Connect walks through enrollment and sends no session facts. Status reads local pairing state and does not confirm server access. Push previews outgoing facts and asks for consent. Disconnect asks to revoke access before removing local pairing after confirmation.

Shared machine facts are sessions and tokens, not provider-billed dollars. Provider credentials are handled separately in Workspace Connections; never paste them into a machine pairing command.

Local analysis reads supported metadata on your machine. CLI usage telemetry is disclosed before sending and includes a random installation identifier and command/runtime information. It excludes report contents, credentials, paths, email addresses and dollar amounts. aibill telemetry displays the last payload; aibill telemetry off, DO_NOT_TRACK, AI_SPEND_NO_TELEMETRY or CI disables it.

Explicit provider sync contacts the selected provider using an inherited environment reference. Explicit Workspace pushes send the approved facts to hosted Workspace. Local MCP returns selected results to the configured AI client under that client's data policy. Reports and report cards are files you choose whether to share. See the privacy policy.

Install the local MCP server when an AI client should query the structured evidence on demand, or build the Glance source preview when you want a compact Mac monitor. Neither replaces the full CLI inspection and Apply workflow.