Integrations

CLI

Manage records, call any endpoint, receive webhooks locally and talk to the AI agent from your terminal.

Overview

The Corebill CLI (@corebill/cli) works like the Stripe CLI: log in with your browser, list and inspect any record in a table, call any API v1 endpoint, forward events to your local server while you build a webhook endpoint, and ask the AI agent to do the work in plain language. Every command has examples in corebill --help.

Bash

 1npm install -g @corebill/cli
 2corebill login
 3corebill invoices --status overdue

Installation

 1npm install -g @corebill/cli   # Node.js 18 or newer
 2corebill --version

corebill login prints a pairing code, opens Corebill in your browser and waits. Check that the code in the browser matches, choose the company and click Authorize. The CLI receives an API key with write access for that company; revoke it anytime in Settings > Developers > API Keys.

Output

 1$ corebill login
 2Your pairing code is: brave-lime-orbit-tide
 3Press Enter to open the browser (^C to quit)
 4Waiting for confirmation in the browser...
 5Done. Connected to Acme Inc as you@acme.com.

Command	Description
`corebill login`	Pairing code + browser
`corebill login --no-browser`	Only print the URL. Over SSH, open it in any browser; no local server is needed
`corebill login --token sk_live_...`	Use an existing API key instead of the browser flow
`corebill whoami`	User, organization, active company and API URL
`corebill logout` / `corebill logout --all`	Disconnect the active company, or every company

Companies

An API key belongs to one company. Log in once per company; the CLI keeps one profile per company and corebill use switches the active one (by id, slug or name).

Output

 1$ corebill companies
 2
 3     Name         Slug         Currency  CLI        ID
 4  >  Acme Inc     acme-inc     USD       connected  com_a1b2c3d4e5f6
 5     Acme Europe  acme-europe  EUR       -          com_f6e5d4c3b2a1
 6
 7Each API key belongs to one company. Connect another one with `corebill login` and switch with `corebill use <company>`.
 8
 9$ corebill use acme-inc
10Active company: Acme Inc com_a1b2c3d4e5f6

corebill status

 1$ corebill status
 2
 3Acme Inc
 4
 5  USD
 6    Collected      $48,250.00
 7    Outstanding    $6,120.00 (7 invoices)
 8    Overdue        $1,980.00 (2)
 9
10  Customers      84 (79 active)

Resource Commands

Each resource lists records in a table, newest first. Pass an id to see one record as JSON. All of them accept --limit (max 100, default 25), --starting-after for the next page and --json for the raw API response.

Command	Module	Filters
`customers [id]`	Core	`--status`, `--query`
`invoices [id]`	Core	`--status`
`quotes [id]`	Core	`--status`
`items [id]`	Core	`--query`
`expenses [id]`	Expenses
`vendors`	Expenses	`--query`
`projects [id]`	Projects	`--status`
`products [id]`	Products	`--query`, `--category`, `--brand`, `--barcode`, `--inactive`
`product-categories`	Products	`--query`
`warehouses`	Inventory	`--include-inactive`
`stock [product_id]`	Inventory	`--warehouse`, `--low-stock`
`purchase-orders [id]`	Purchases	`--status`, `--vendor`
`bills [id]`	Purchases	`--status`, `--vendor`, `--overdue`
`cash-registers`	Cash	`--inactive`
`cash-sessions [id]`	Cash	`--status`, `--register`
`cash-movements`	Cash	`--session`, `--register`, `--direction`, `--source`
`pos-sales [id]`	Point of sale	`--status`, `--session`, `--register`, `--customer`, `--since`
`work-orders [id]`	Work orders	`--status`, `--query`, `--customer`, `--assigned-to` (id or `order_number`)

Output

 1$ corebill invoices --status overdue --limit 3
 2
 3  Number           Status   Issued      Due         Total      Amount due  ID
 4  INV-2026-000041  overdue  2026-09-02  2026-09-17  $1,200.00  $1,200.00   inv_b2c3d4e5f6g7h8i9
 5  INV-2026-000037  overdue  2026-08-20  2026-09-04  $780.00    $780.00     inv_c3d4e5f6g7h8i9j0
 6  INV-2026-000033  overdue  2026-08-11  2026-08-26  $2,400.00  $1,400.00   inv_d4e5f6g7h8i9j0k1
 7
 8  More results available. Next page: corebill invoices --starting-after inv_d4e5f6g7h8i9j0k1

Output

 1$ corebill stock --low-stock
 2
 3  Code        Product          Quantity  Unit  Reorder at  Value    Warehouses                   Product ID
 4  PRD-000012  USB-C cable 2m   8         unit  10          $33.60   Main warehouse 5, Store 3    itm_9f2c1a
 5  PRD-000019  HDMI adapter     2         unit  5           $14.00   Main warehouse 2             itm_7c1e2b
 6
 7$ corebill work-orders --status in_progress
 8
 9  Number     Title               Customer          Status       Delivery    Total    Pending  ID
10  WO-000057  Screen replacement  Acme Corporation  in_progress  2026-10-18  $180.00  $130.00  wo_a1b2c3d4e5f6

Commands of optional modules need the module on in Settings > Modules. If it is off, the CLI says so instead of failing with a raw error.

Retrieve one record

Output

 1$ corebill work-orders WO-000057
 2{
 3  "id": "wo_a1b2c3d4e5f6",
 4  "object": "work_order",
 5  "order_number": "WO-000057",
 6  "title": "Screen replacement",
 7  "status": "in_progress",
 8  "total_amount": 180,
 9  "paid_amount": 50,
10  "pending_amount": 130,
11  ...
12}

JSON output

--json prints the exact API response, so you can pipe it into jq. Output has no colors when it is not a terminal.

Bash

 1corebill invoices --status overdue --json | jq -r '.data[] | "\(.invoice_number) \(.amount_due)"'
 2corebill bills --overdue --json | jq '[.data[].amount_due] | add'
 3corebill products --barcode 7750000000012 --json | jq '.data[0].id'

Calling Any Endpoint

corebill get, post, patch and delete call any API v1 path (with or without the /v1 prefix). Add fields with -d key=value (repeatable) or send a raw body with --json. On get, fields become query params.

Bash

 1# GET with query params
 2corebill get /customers -d query=acme -l 5
 3corebill get /invoices/inv_b2c3d4e5f6g7h8i9
 4corebill get /events -d type=invoice.* -d limit=50
 5
 6# POST
 7corebill post /customers -d name="Acme Corp" -d contact_email=billing@acme.com
 8corebill post /invoices/inv_b2c3d4e5f6g7h8i9/record_payment -d amount=150 -d payment_method=bank_transfer
 9
10# PATCH and DELETE
11corebill patch /customers/cus_a1b2c3d4e5f6g7h8 -d contact_phone="+1 555 0100"
12corebill delete /items/itm_123

Nested fields and lists

Use bracket notation for objects and arrays: a[b]=x builds { "a": { "b": "x" } } and lines[0][quantity]=2 builds an array of objects. true, false, null and numbers are sent as JSON types.

Bash

 1corebill post /invoices \
 2  -d customer_id=cus_a1b2c3d4e5f6g7h8 \
 3  -d "line_items[0][item_name]=Design" \
 4  -d "line_items[0][quantity]=10" \
 5  -d "line_items[0][unit_price]=80" \
 6  -d "line_items[1][item_name]=Hosting" \
 7  -d "line_items[1][unit_price]=25" \
 8  -d "metadata[order_id]=6735"
 9
10corebill post /stock/adjustments \
11  -d warehouse_id=wh_7k2 \
12  -d "lines[0][product_id]=itm_9f2c1a" \
13  -d "lines[0][quantity]=-2"
14
15# Or the whole body as JSON
16corebill post /quotes --json '{"customer_id":"cus_a1b2c3d4e5f6g7h8","line_items":[{"item_name":"Audit","unit_price":900}]}'

POST requests get an Idempotency-Key automatically; pass --idempotency-key to set your own so a retry never creates a duplicate.

corebill listen

Follows the events of the active company in real time and, with --forward-to, sends each one to your local server signed like a real webhook. The Events page has the full walkthrough, including how to verify the signature.

Test webhooks locally

Forward events to localhost and verify the whsec_ signature.

Output

 1$ corebill listen --forward-to localhost:3000/webhooks/corebill
 2Ready! Listening for events on Acme Inc. Your webhook signing secret is whsec_3f9c0a7e1b2d4c6f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d (^C to quit)
 3Forwarding events to http://localhost:3000/webhooks/corebill
 4
 52026-10-11 14:03:22  --> invoice.paid [evt_8f2c1a9b7d3e4f56a1b2c3d4e5f6a7b8] inv_b2c3d4e5f6g7h8i9
 62026-10-11 14:03:22  <-- [200] POST http://localhost:3000/webhooks/corebill [evt_8f2c1a9b7d3e4f56a1b2c3d4e5f6a7b8]
 72026-10-11 14:04:01  --> stock.low [evt_2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f] itm_9f2c1a
 82026-10-11 14:04:01  <-- [ERR] POST http://localhost:3000/webhooks/corebill [evt_2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f] ECONNREFUSED

Option	Description
`-f, --forward-to`	POST each event to this URL (`http://` is added if missing)
`-e, --events`	Comma separated types, wildcards allowed (`invoice.*,payment.received`)
`-j, --print-json`	Print the full JSON of each event
`--print-secret`	Print the local signing secret (`whsec_...`) and exit
`-i, --interval`	Polling interval (default 2)

Forwarded requests send the webhook envelope (id, event, created_at, data, metadata, test) with Content-Type: application/json, User-Agent: corebill-cli/ and Corebill-Signature: t=,v1=.">. The whsec_... secret is generated once per company on your computer and does not change.

corebill trigger

Creates a test event with the example payload of the type. Test events are never delivered to your real webhook endpoints; receive them with corebill listen.

Output

 1$ corebill trigger invoice.paid
 2Triggered invoice.paid (evt_8f2c1a9b7d3e4f56a1b2c3d4e5f6a7b8). Run `corebill listen` to receive it.
 3
 4$ corebill trigger --list
 5
 6Invoice
 7  invoice.created         A draft invoice was created.
 8  invoice.issued          An invoice left draft and got its final number.
 9  invoice.paid            An invoice was paid in full.
10  ...
11
12Work order
13  work_order.created      A new work order was opened.
14  work_order.delivered    A work order was delivered to the customer.
15
16Trigger one with `corebill trigger <event>`, e.g. corebill trigger invoice.paid

corebill events

Output

 1$ corebill events --type invoice.* --limit 3
 2
 3  ID                                   Type             Resource              Created
 4  evt_8f2c1a9b7d3e4f56a1b2c3d4e5f6a7b8  invoice.paid     inv_b2c3d4e5f6g7h8i9  2026-10-11 14:03:22
 5  evt_7e1b0a8c6d2f3e45b0a1c2d3e4f5a6b7  invoice.issued   inv_b2c3d4e5f6g7h8i9  2026-10-09 10:12:40
 6  evt_6d0a9b7c5e1f2d34a9b0c1d2e3f4a5b6  invoice.created  inv_b2c3d4e5f6g7h8i9  2026-10-09 10:11:05
 7
 8$ corebill events --resource inv_b2c3d4e5f6g7h8i9
 9$ corebill events evt_8f2c1a9b7d3e4f56a1b2c3d4e5f6a7b8   # one event as JSON

corebill ask

Talk to the Corebill AI agent: one question, or an interactive chat without arguments. It can create quotes and invoices, record payments and answer questions about your data, and it needs a key with write access.

Bash

 1corebill ask "which invoices are overdue?"
 2corebill ask "create a quote for Acme with 10 hours of design at $80"
 3corebill ask "send invoice INV-2026-0012 to the customer"
 4corebill ask   # interactive chat

Utilities

Command	Description
`corebill open`	Open the dashboard
`corebill open docs` / `corebill open api`	Open the docs or the API reference
`corebill config`	Print the path of the configuration file (profiles and local secrets)
`corebill --help` / `corebill --help`	Commands grouped by section, with examples

CI and Scripts

Set COREBILL_API_KEY and every command uses that key instead of the logged-in company. No corebill login needed.

 1- name: Export overdue invoices
 2  run: npx @corebill/cli invoices --status overdue --json > overdue.json
 3  env:
 4    COREBILL_API_KEY: ${{ secrets.COREBILL_API_KEY }}

Environment Variables

Variable	Description
`COREBILL_API_KEY`	Use this key instead of the logged-in company (CI, scripts)
`COREBILL_API_URL`	API base, with or without `/v1` (default `https://api.corebill.io`)
`COREBILL_APP_URL`	Web app used by `login` and `open` (default `https://app.corebill.io`)

Troubleshooting

Message	What to do
Not authenticated. Run `corebill login` first.	No profile and no `COREBILL_API_KEY`. Log in or set the variable
Authentication failed (401)	The key was revoked or is invalid. Run `corebill login` again, or check `COREBILL_API_KEY`
Permission denied (403 `permission_required`)	The key is `read` only. Writing needs `write`; deleting and module configuration need `admin`
The X module is turned off for this company (403 `module_disabled`)	An owner or admin enables it in Settings > Modules
Rate limited (429)	Wait for the `Retry-After` seconds; lower the `listen` frequency with `--interval`
Connection failed	Check your network and `COREBILL_API_URL`
`<-- [ERR]` in `listen`	Your local server is not running or the `--forward-to` URL is wrong; the listener keeps running

Node.js SDK AI Agent

CLI

Overview

Installation

Log In

Companies

Resource Commands

Retrieve one record

JSON output

Calling Any Endpoint

Nested fields and lists

corebill listen

corebill trigger

corebill events

corebill ask

Utilities

CI and Scripts

Environment Variables

Troubleshooting