--- name: billingnow-cli description: Use BillingNow CLI (bn) for invoicing, billing, payments, and financial management. Use this skill when users ask to create invoices, manage bills, record payments, handle clients/suppliers, generate reports, or work with estimates and credit notes via command line. --- # BillingNow CLI The BillingNow CLI (`bn`) provides command-line access to BillingNow's invoicing and billing platform. Use Bash to execute these commands. ## Authentication If a command fails with an unauthorized error (401), authenticate with: ```bash bn login # Opens browser for OAuth authentication ``` ## Command Reference All commands support `-f json` for machine-readable output. Use `--help` on any command for details. ### Invoices ```bash # List invoices bn invoice list bn invoice list --status sent bn invoice list --relation # Get invoice by ID bn invoice get # Find invoice by ID or invoice number bn invoice find INV-001 bn invoice find # Create invoice (items format: JSON array) bn invoice create --relation --items '[{"name":"Service","quantity":1,"netPrice":100}]' bn invoice create --relation --items '' --date 2025-01-15 --due-date 2025-02-15 # Update invoice bn invoice update --items '' bn invoice update --due-date 2025-02-28 # Change status (draft, not-sent, sent, overdue, cancelled) bn invoice status sent # Delete invoice bn invoice delete # Generate invoice number bn invoice generate-number ``` **Invoice statuses**: draft, not-sent, sent, overdue, partially-paid, paid, refunded, cancelled **Important**: `paid` and `partially-paid` statuses can ONLY be set via the payment system, not manually. ### Bills (Expenses) ```bash # List bills bn bill list bn bill list --status pending bn bill list --relation # Get bill by ID bn bill get # Find bill by ID or bill number bn bill find BILL-001 bn bill find # Create bill bn bill create --relation --total 500 bn bill create --relation --total 500 --subtotal 450 --tax-amount 50 --date 2025-01-15 # Update bill bn bill update --total 600 --note "Updated amount" # Change status (draft, pending, overdue) bn bill status pending # Bill analysis (for uploaded receipts) bn bill analyze # Check analysis status bn bill confirm # Confirm extracted data bn bill retry # Retry failed analysis # Delete bill bn bill delete ``` **Bill statuses**: draft, pending, overdue, partially-paid, paid ### Payments ```bash # List payments bn payment list bn payment list --invoice bn payment list --bill bn payment list --transaction-type credit # Get payments for an entity bn payment get # Create payment (required: --amount + one of --invoice/--bill/--credit-note) bn payment create --invoice --amount 500 bn payment create --bill --amount 300 --method cash --date 2025-01-20 bn payment create --credit-note --amount 100 # Update payment bn payment update --amount 550 --method bank_transfer # Delete payment bn payment delete ``` **Payment methods**: bank_transfer, card, cash, check, other ### Relations (Clients/Suppliers) ```bash # List relations bn relation list bn relation list --type client bn relation list --type supplier # Get relation by ID bn relation get # Find relation by ID or name bn relation find "Acme Inc" bn relation find # Create an organization (company) relation bn relation create --org --org-name "Acme Inc" --currency USD bn relation create --org --org-name "Supplier Co" --org-tax "CHE-123.456.789" --currency EUR --type supplier --email contact@supplier.com # Create an individual (person) relation bn relation create --first-name "John" --last-name "Doe" --email "john@example.com" --currency USD bn relation create --prefix "Mr." --first-name "John" --last-name "Smith" --email "john@smith.com" --currency CHF --type client # Create with full details bn relation create --org --org-name "Company Inc" --currency USD \ --address-line1 "123 Main St" --city "New York" --state "NY" --zipcode "10001" --country "USA" \ --payment-term 45 --note "Key client" # Update relation bn relation update --email new@email.com bn relation update --org-name "New Company Name" --org-tax "VAT123456" bn relation update --first-name "Jane" --last-name "Doe" bn relation update --address-line1 "456 Oak Ave" --city "Boston" --country "USA" bn relation update --payment-term 60 --note "Updated terms" # Delete relation bn relation delete ``` **Relation types**: client, supplier, both **Creating organizations** (companies): Use `--org --org-name ` with optional `--org-tax ` **Creating individuals** (persons): Use `--first-name --last-name --email ` (all required), optional `--prefix ` **Common options**: `--currency ` (required), `--type `, `--address-line1`, `--address-line2`, `--city`, `--state`, `--zipcode`, `--country`, `--payment-term ` (default: 30), `--note ` ### Estimates (Quotes) ```bash # List estimates bn estimate list bn estimate list --status sent # Get estimate by ID bn estimate get # Find estimate by ID or estimate number bn estimate find EST-001 bn estimate find # Create estimate bn estimate create --relation --items '[{"name":"Consulting","quantity":10,"netPrice":150}]' bn estimate create --relation --items '' --valid-until 2025-02-28 # Update estimate bn estimate update --valid-until 2025-03-15 # Change status bn estimate status sent bn estimate status approved # Delete estimate bn estimate delete ``` **Estimate statuses**: draft, sent, approved, rejected ### Credit Notes ```bash # List credit notes bn credit-note list bn credit-note list --status sent # Get credit note by ID bn credit-note get # Find credit note by ID or credit note number bn credit-note find CN-001 bn credit-note find # Create credit note bn credit-note create --relation --items '[{"name":"Refund","quantity":1,"netPrice":50}]' bn credit-note create --relation --items '' --invoices inv-id1,inv-id2 # Update credit note bn credit-note update --items '' # Change status bn credit-note status sent # Delete credit note bn credit-note delete ``` **Credit note statuses**: draft, not-sent, sent, applied, cancelled ### Recurring Invoices ```bash # List recurring templates bn recurring-invoice list bn recurring-invoice list --active # Get template by ID bn recurring-invoice get # Find template by ID or name bn recurring-invoice find "Monthly Retainer" bn recurring-invoice find # Create recurring template bn recurring-invoice create --name "Monthly Retainer" --relation --frequency monthly \ --items '[{"name":"Monthly Service","quantity":1,"netPrice":1000}]' # Update template bn recurring-invoice update --frequency weekly --next-issue-date 2025-02-01 # Toggle active/inactive bn recurring-invoice toggle --active bn recurring-invoice toggle --inactive # Manually generate invoice from template bn recurring-invoice generate # Delete template bn recurring-invoice delete ``` **Frequencies**: daily, weekly, monthly, yearly, custom **End types**: never, after_occurrences, by_date ### Catalog Items ```bash # List items bn item list bn item list --active # Get item by ID bn item get # Find item by ID, name, or SKU bn item find "Web Development" bn item find LOGO-001 bn item find # Create item bn item create --name "Web Development" --net-price 150 --currency USD bn item create --name "Logo Design" --net-price 500 --currency EUR --sku LOGO-001 # Update item bn item update --net-price 175 --active bn item update --inactive # Delete item bn item delete ``` ### Tax Rates ```bash # List taxes bn tax list # Get tax by ID bn tax get # Find tax by ID or designation bn tax find "VAT 20%" bn tax find # Create tax bn tax create --designation "VAT 20%" --rate 20 bn tax create --designation "Sales Tax" --rate 8.5 --default # Update tax bn tax update --rate 21 --default # Delete tax bn tax delete ``` ### Categories ```bash # List categories bn category list # Get category by ID bn category get # Find category by ID or name bn category find "Consulting" bn category find # Create category bn category create --name "Consulting" --color "#3B82F6" # Update category bn category update --name "Consulting Services" # Delete category bn category delete ``` ### Reporting ```bash # Activity report (all document types) bn reporting activity --period this-month bn reporting activity --relation --invoice-status paid,sent # Sales reports bn reporting sales --period last-month bn reporting sales-per-date --years 2024,2025 --display-by monthly bn reporting sales-per-client --period this-year bn reporting sales-per-items --period this-month # Payment reports bn reporting payments --period this-month --transaction-type credit bn reporting payments-per-date --years 2024,2025 bn reporting payments-per-relation --period this-year bn reporting payments-per-type --period this-month # Expense reports bn reporting expenses --period this-month bn reporting expenses-per-date --years 2024,2025 bn reporting expenses-per-relation --period this-year # Tax reports bn reporting tax --years 2024,2025 --display-by quarterly bn reporting tax-per-designation --period this-year # Get available years for reporting bn reporting years ``` **Periods**: this-month, last-month, this-year, last-year, custom (requires --start-date and --end-date) **Display groupings**: monthly, quarterly, yearly ### Organization ```bash # List organizations bn org list # Get active organization bn org active # Get specific organization bn org get # Switch organization bn org switch # Update organization bn org update --name "My Company" --email contact@company.com bn org update --timezone "America/New_York" --country "USA" # Get invoice template settings bn org template # Update template settings bn org template-update --invoice-prefix "INV-" --payment-terms "Net 30" ``` ### Authentication & API Keys ```bash # Login (opens browser) bn login bn login --key # Direct API key login # Logout bn logout # Show current user bn whoami # Manage API keys bn keys list bn keys create --name "CI/CD Key" bn keys create --name "Temp Key" --expires 2025-06-01 bn keys revoke ``` ### Configuration ```bash # View config bn config list bn config get baseUrl bn config path # Set config bn config set baseUrl https://api.billingnow.com ``` ## Line Item Format Items for invoices, estimates, credit notes, and recurring invoices use JSON format: ```json [ { "name": "Service Name", "quantity": 1, "netPrice": 100, "description": "Optional description", "taxId": "optional-tax-id" } ] ``` Example with multiple items: ```bash bn invoice create --relation --items '[ {"name":"Consulting","quantity":5,"netPrice":150}, {"name":"Development","quantity":20,"netPrice":100} ]' ``` ## Common Workflows ### Create and Send Invoice ```bash # Get client ID bn relation list --type client -f json # Create invoice bn invoice create --relation --items '[{"name":"Service","quantity":1,"netPrice":500}]' # Mark as sent bn invoice status sent ``` ### Record Payment for Invoice ```bash # Get invoice details to see amount bn invoice get # Create payment bn payment create --invoice --amount 500 --method bank_transfer ``` ### Generate Sales Report ```bash bn reporting sales --period this-month -f json bn reporting sales-per-client --period this-year ``` ## Tips - Use `-f json` for programmatic output parsing - Due dates default to invoice date + client's payment term (default 30 days) - Currency defaults to organization's currency - Invoice/bill numbers are auto-generated if not specified - All IDs are UUIDs