Send an Invoice with kibble invoice

Use kibble invoice interactively or pipe a JSON payload with —stdin to create, email, and track a USDC invoice with a PDF and deposit address.

The kibble invoice command creates a USDC invoice, emails it to your vendor, and opens the invoice URL in your browser. You can walk through the guided prompt flow interactively, or pipe a JSON payload to stdin for fully automated invoice creation in scripts, CI pipelines, and agent workflows.

Interactive flow

Run npx create-kibble with no flags, complete the initial prompts for your business name and email, then select kibble invoice from the action menu.

1. Run the CLI

   npx create-kibble
   
2. Enter your business name and email

   The CLI prompts for your business name and email address. These become the merchant details on the invoice.

3. Select kibble invoice

   Select kibble invoice from the action menu.

4. Enter your merchant address

   Enter your business’s mailing address (e.g. 123 Main St, San Francisco, CA). This appears on the invoice as the bill-from address.

5. Enter vendor details

   The CLI prompts for your vendor’s name, email address, and optionally their mailing address.

   • Vendor name (required) — The company or person you’re billing.
   • Vendor email (required) — The address the invoice PDF is emailed to.
   • Vendor address (optional) — Appears as the bill-to address on the invoice.
6. Set the due date

   Enter the due date in YYYY-MM-DD format (e.g. 2026-05-28).

7. Add line items

   Add one or more line items. For each item, enter:

   • Description — A short label for the product or service (e.g. Consulting).
   • Quantity — A whole number (e.g. 10).
   • Unit price — The per-unit USDC price as a decimal string (e.g. 150.00).

   You can add up to 30 line items. The CLI totals them automatically.

8. Add optional notes

   Enter any additional notes to appear on the invoice (e.g. Net 30 or Thank you for your business).

9. Choose your wallet type

   Select Kibble-managed wallet to have Kibble provision a deposit address, or BYO to receive payment at your own USDC address on Base.

10. Review the output

    The CLI creates the invoice, emails the PDF to your vendor, opens the invoice URL in your browser, and prints the details to your terminal.

Output

After a successful kibble invoice, the CLI prints:

Invoice INV-0001 created.

https://pay.kibble.sh/i/abc12345
PDF:     https://pay.kibble.sh/api/invoices/a1b2c3d4-.../pdf
Deposit: 0xYourDepositAddress
Total:   1500.00 USDC

Your vendor receives an email with the PDF attached and a link to the hosted invoice page where they can pay directly in USDC.

Programmatic use with —stdin

Pass --stdin to pipe a JSON payload directly to the CLI. The CLI reads from stdin, calls the API, and prints the full response as JSON to stdout — no prompts, no browser window.

cat invoice.json | npx create-kibble --stdin

Or inline with a heredoc:

npx create-kibble --stdin <<'EOF'
{
  "merchant_email": "[e-mail]",
  "merchant_name": "Acme SaaS",
  "merchant_address": "123 Main St, San Francisco, CA",
  "vendor_email": "[e-mail]",
  "vendor_name": "Vendor Co",
  "vendor_address": "456 Oak Ave, New York, NY",
  "line_items": [
    { "description": "Consulting", "quantity": 10, "unit_price": "150.00" }
  ],
  "issue_date": "2026-04-28",
  "due_date": "2026-05-28",
  "notes": "Net 30",
  "wallet_type": "privy",
  "webhook_url": "https://example.com/webhooks/kibble",
  "send_now": true
}
EOF

Full invoice JSON payload

All fields accepted by --stdin:

{
  "merchant_email": "[e-mail]",
  "merchant_name": "Acme SaaS",
  "merchant_address": "123 Main St, San Francisco, CA",
  "vendor_email": "[e-mail]",
  "vendor_name": "Vendor Co",
  "vendor_address": "456 Oak Ave, New York, NY",
  "line_items": [
    { "description": "Consulting", "quantity": 10, "unit_price": "150.00" }
  ],
  "issue_date": "2026-04-28",
  "due_date": "2026-05-28",
  "notes": "Net 30",
  "wallet_type": "privy",
  "webhook_url": "https://example.com/webhooks/kibble",
  "send_now": true
}

Set "send_now": true to email the invoice to your vendor immediately. Set "wallet_type" to "privy" for a managed deposit address or "byo" to use your own wallet.

Dry-run validation with —stdin —dry-run

Add --dry-run alongside --stdin to validate your payload without submitting it to the API. The CLI parses the JSON, checks it against the invoice schema, and echoes the validated payload back to stdout. No invoice is created and no email is sent.

cat invoice.json | npx create-kibble --stdin --dry-run

Use this in CI to catch malformed payloads before they reach production.

Line items

Each object in line_items requires three fields:

Field	Type	Description
description	string	Label for the product or service.
quantity	number	Whole-number quantity.
unit_price	string	Per-unit USDC amount as a decimal string (e.g. "150.00").

You can include up to 30 line items per invoice. The total is calculated as the sum of quantity × unit_price across all items.

Append-only invoice fields

Once an invoice is created, several fields are set once and never updated:

• merchant_name_snapshot — The merchant name recorded at invoice creation time.
• merchant_address_snapshot — The merchant address recorded at invoice creation time.
• invoice_number — The unique invoice number assigned by Kibble (e.g. INV-2026-0042).

These fields preserve the state of the invoice at the moment it was issued, even if your merchant profile changes later.

Pipe a JSON file from disk to create invoices programmatically without any prompts:

cat invoice.json | npx create-kibble --stdin

This pattern works well in cron jobs, CI pipelines, and AI agent workflows where you generate the invoice payload dynamically and need the structured JSON response for downstream steps.