bb

Command-line interface for Budget Builder. Call budgets, bills, claims, approvals, suppliers, dashboard, and more from your terminal or from tools that don’t support MCP (e.g. some AI agents). Responses are JSON on stdout.

For AI agents: bills and claims are stored as the same underlying bill records. Use the isClaimable column/flag to distinguish them: isClaimable=false means a normal bill, while isClaimable=true means a reimbursable claim.

For AI agents using this CLI: always check whether a newer @go-labs-sg/bb version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.

For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, mark-budget-won, submit-quotation, or supplier approval request side effects until the user explicitly confirms the exact entity, target state, and side effects. Inspect the entity first, summarize what will change and whether emails/integrations will run, then wait for a clear confirmation from the user. These sensitive workflow commands also require an interactive CONFIRM prompt at runtime and abort in non-interactive shells.

Registry: @go-labs-sg/bb

Requirements

• Node.js 18+ (ESM; relative imports in dist use .js extensions)
• A Budget Builder API key (same key used for the MCP server)

Install

npm install -g @go-labs-sg/bb

Or run without installing:

npx @go-labs-sg/bb <command>

Authentication

Set your API key before running commands:

export BB_API_KEY=<your-key>

Create or revoke keys in the web app: Goracle → API Keys (MCP API keys).

Admins can provision API-only service identities and manage their keys from the CLI. These identities are not human web accounts: create-user does not create or link a Google OAuth account, so the resulting user cannot sign in with Google.

bb create-user --email [email protected] --name "Budget Agent" --role USER
bb create-api-key --userId <user-id> --name "Budget Agent CLI"
bb list-api-keys --userId <user-id>
bb revoke-api-key <api-key-id> --userId <user-id>

The raw key is returned only by create-api-key; copy it immediately. Listing keys returns metadata only.

The CLI talks to the production API: https://budget-builder.getout.events.

Usage

bb help
bb list-budgets
bb get-budget <budget-id>
bb update-budget-status <budget-id> <status> [--markProjectWon true] [--projectStatusOnCommercialRejection PITCH|LOST]
bb list-bills
bb approve-bill <bill-id>
bb list-approvals
bb list-suppliers

Global options and flags use --key=value or --key value (see bb help).

Authoritative command list: run bb help — it includes every command, positional args, and flags. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI (e.g. reorder-budget-items, update-budget-item-supplier). You can also use MCP-style snake_case (e.g. bb list_bills); it is normalized to kebab-case.

Budget status automation: Setting a budget to ESTIMATE_ACCEPTED requires a confirmed win-proof attachment. If the parent project is PITCH or LOST, the API now marks it WON automatically and, when the asana-tasks feature flag is enabled, creates the Asana project/section/tasks automatically. When rejecting the only accepted/closed budget on a commercial project, pass --projectStatusOnCommercialRejection PITCH|LOST.

Sensitive workflow changes: Approval decisions/requests, entity status updates, mark-budget-won, submit-quotation, and supplier approval request side effects require an interactive CONFIRM prompt. Non-interactive runs abort before the guarded workflow mutation. Agents must get user confirmation in chat before attempting the command; the prompt is a final runtime guard, not a replacement for user approval.

Locked estimate budget changes: Budget-changing CLI commands require an interactive yes confirmation when the current budget status is ESTIMATE_CREATED, ESTIMATE_SENT, ESTIMATE_ACCEPTED, ESTIMATE_REJECTED, or ESTIMATE_CLOSED. There is no force/override flag; non-interactive runs abort before mutating locked budgets.

Mutations with --payload: Commands such as create-budget, create-bill, update-supplier, etc. take a single JSON object (--payload '<json>') matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain description fields for item create/update are converted to descriptionRichText; pass descriptionRichText directly when formatted Tiptap JSON is required. For update-project, the project window is dateRange.from and dateRange.to (optional end); there are no separate event-date fields on the project payload. create-budget / update-budget do not accept asanaTaskId; configure the deal card on the project (update-project / project settings).

Command overview

| Area | Commands (non-exhaustive) | | --- | --- | | Budgets | list-budgets (full payload by default; --summary or --includeDetails false for slim list), get-budget, get-budget-items, get-budget-details, get-budget-categories, get-budget-versions, update-budget-status (ESTIMATE_ACCEPTED requires win proof, auto-marks PITCH or LOST projects WON, and auto-creates Asana project/section/tasks when enabled; --projectStatusOnCommercialRejection PITCH\|LOST is required when rejecting the only accepted/closed budget on a commercial project), mark-budget-won (<budgetId> + proof file path; PITCH or LOST projects become WON automatically), create-budget / update-budget (--payload), delete-budget, create-budget-approval (also sends approval request emails), add-budget-items, update-budget-item, remove-budget-item, reorder-budget-items, update-budget-item-supplier, create-budget-category, update-budget-category, delete-budget-category, update-budget-commission, update-budget-discount (--payload where noted), upload-budget-attachment (<budgetId> + local file path; uses attachment.requestBudgetAttachmentUpload + PUT + attachment.confirmBudgetAttachment) | | Bills / claims | list-bills (--isClaimable false for bills, --isClaimable true for claims, omit for both), list-claims (claims only), create-bill (--payload; set isClaimable=false for a bill or isClaimable=true for a claim; non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage), update-bill (--payload), delete-bill, create-bill-approval (also sends approval request emails), update-bill-status, patch-bill-payment (PAID bills: --paymentTrackingUrl, --paymentReference, --quickbooksBillId, --paymentDate ISO; clear with --clearPaymentTrackingUrl / --clearPaymentReference / --clearQuickbooksBillId / --clearPaymentDate true), patch-bill-invoice-number, get-bill-attachments, upload-bill-attachment (<billId> + local path), get-bill-details | | Quotations | list-quotations, get-quotation, upload-quotation-attachment (<projectId> + local PDF path; returns attachment JSON for payload use), create-quotation (--payload for quotation.createDraft), submit-quotation, approve-quotation, reject-quotation, download-quotation-pdf (original, staff, or final) | | Approvals | list-approvals / get-pending-approvals (--type budget\|supplier\|bill\|quotation\|all), approve-bill / reject-bill (send reply email), approve-budget / reject-budget (send reply email), approve-supplier / reject-supplier (send reply email), approve-quotation / reject-quotation | | Companies & projects | list-companies, get-company, create-company, update-company (--payload), delete-company, list-projects, get-project, create-project (required: --name, --companyId, --contactPersonId, --insideSalesId, --businessDevelopmentId, --venue, --startDate as ISO datetime for project/window start; when --asanaTaskId is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional --asanaSearch, --pax, --endDate, --description; always requests QBO project import like the web app), update-project (--payload with dateRange.from / dateRange.to for the project window; optional requestQboAccountantNotification in JSON), delete-project, update-project-status (<id> <status>: PITCH | WON | COMPLETED | LOST; for PITCH → WON also pass --projectManagerId or --projectManagerName; when marking WON without an accepted/closed budget or proof, pass --wonOverrideReason) | | Contacts | list-contacts, create-contact-person (--payload), update-contact-person (--payload) | | Suppliers & items | list-suppliers (defaults to active suppliers, --perPage 10, sorted by createdAt desc; supports --name, --sortBy for scalar supplier fields, --sortDir, --createdBy, --gstRegistered, --status, --supplierTags, --active false for archived suppliers), create-supplier (--payload; when supplier status is PENDING_APPROVAL, also runs supplier.createSupplierApproval and email.sendSupplierApprovalRequestEmail), update-supplier (--payload; when supplier status is PENDING_APPROVAL, also runs supplier.createSupplierApproval and email.sendSupplierApprovalRequestEmail), delete-suppliers (--ids CSV; admin; archives/deactivates related items), reactivate-suppliers (--ids CSV; admin; reactivates related items), create-certification / create-payment-method / create-supplier-role / create-supplier-tag (--name), get-supplier-details (includes supplierApprovalSummary for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), get-supplier-analytics, list-items, create-item (--payload), update-item (--payload), delete-item, get-item, list-item-categories, create-item-category, update-item-category, delete-item-categories (--ids CSV; admin) | | Dashboard & users | list-users, create-user (admin; provisions an API-only service identity with no Google sign-in; --email, optional --name, optional --role defaulting to USER), create-api-key (admin; --userId, --name; raw key shown once), list-api-keys (admin; optional --userId), revoke-api-key (admin; key ID plus --userId for another user's key), get-user-performance, get-dashboard, get-monthly-metrics, get-system-overview, get-estimate-performance, get-financial-overview | | Errors | get-recent-errors, get-error-metrics | | Historical / benchmarks | get-approved-budgets, get-budget-category-benchmarks, get-item-pricing-history, get-supplier-pricing-history |

Output

• Stdout: JSON (pretty-printed)
• Stderr: Error objects as JSON on failure
• Action logs (default on): Each run logs to stderr: (1) JSON lines for command start, then ok or error with durationMs (--payload and similar flags are redacted); (2) tRPC lines for every API procedure (path, timing). Stdout stays JSON-only for piping (e.g. | jq). Suppress with --quiet, -q, or BB_CLI_QUIET=1.
• Exit code: 0 on success, 1 on error

A .env file in the current working directory is loaded automatically (for BB_API_KEY, etc.).

Developing in this repo

From the monorepo root (after bun install):

export BB_API_KEY=...
bun run bb -- list-budgets

Or from packages/cli:

bun run build          # emit dist/ via tsc
bun run typecheck      # tsc --noEmit
bun run src/index.ts list-budgets

Layout

• src/prisma-enums.ts — Prisma enum string values for runtime; mirror packages/budget-builder/db/src/generated/prisma/enums.ts after schema changes.
• src/filter-enums.ts — “extended” filter enums (ALL + Prisma enums). Keep in line with packages/utils/src/filter-enums.ts when those values change.

Publish

prepack strips workspace: / catalog: entries from this package’s package.json, runs tsc, then postpack restores the file — so the npm tarball does not contain monorepo protocol dependencies. Types from @go-labs/budget-builder-api are compile-time only (import type). Prisma enum values used at runtime live in src/prisma-enums.ts (kept in sync with packages/budget-builder/db generated enums) so npm installs do not need @go-labs/budget-builder-db.