@fluid-app/fluid-cli-billing

Fluid CLI plugin for company billing: invoices, payments, credits and spend limits.

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-billing
fluid login
fluid billing show                              # invoices, upcoming charge, payment method
fluid billing update --email [email protected] --yes
fluid billing standing
fluid billing payments --limit 20
fluid billing payments invoice 512 --open       # fresh Stripe link; they expire
fluid billing documents
fluid billing documents link 409 --open
fluid billing credits                           # balance, plan, prices
fluid billing credits quote 1000                # whole dollars
fluid billing credits buy 1000 --yes            # spends real money
fluid billing credits purchases
fluid billing credits movements --limit 50
fluid billing credits pay-now --yes             # spends real money
fluid billing credits plan growth --interval annual --yes
fluid billing limits
fluid billing limits set --limits on --ai-monthly 1500 --ai-daily 100 --yes
fluid billing usage record --sku sms_send --quantity 42 --dedup-key batch-7 --yes

Every command prints JSON; amounts are the API's integer cents, as it sent them. Failures print a JSON error (and the API's code, such as quote_changed) on stderr and exit non-zero. Anything that changes billing or charges the saved payment method asks for confirmation, or needs --yes when there is no terminal. buy and pay-now show the quoted total, card fee included, in that question; buy sends the quote back so the server refuses it if the price, terms or payment method changed. credits plan asks with the monthly total the plan will charge from the 1st, priced as Fluid prices it (the catalog or chosen price, the annual discount and the card fee), and changes nothing when it can't price the choice. It sends the monthly charge and total it showed, so if another admin changes the plan, or the saved payment method becomes a card, meanwhile, the server refuses the choice (code: "plan_charge_changed") and nothing is saved. While the saved card's type is still being checked, no plan can be chosen (code: "card_funding_pending"); try again in a few minutes. If a buy fails without a clear answer, retry with the --purchase-key it printed rather than buying again.

buy and pay-now print the purchase the API returned. The API answers the same way whatever the charge's outcome, so the CLI reads its status. Any other outcome than success or pending prints the purchase, then a JSON error on stderr with charge_status and a code, and exits non-zero: charge_declined for failed (with the decline reason when Stripe gave one), charge_refunded for refunded, charge_reversed for reversed, and charge_<status> for any other status (charge_unknown when there is none). A pending or processing charge (a bank debit takes about 4 business days) exits 0 with pending: true and a note; fluid billing credits purchases shows the outcome later.

--open opens only Stripe https links (the hosted invoice page and the invoice and credit note PDFs). opened is true once the system opener finished cleanly, "attempted" if it was still running after a few seconds, and false with an open_error when there is no opener (a headless box without xdg-open, say) or it failed; the link is printed either way.

Commands that need fluid login

Changes that record who made them need a signed-in user. A company (C-) or partner token is refused with a 403 for these, even when its role holds billing.update:

• fluid billing credits buy
• fluid billing credits pay-now
• fluid billing credits plan
• fluid billing limits set

Run fluid login as a company admin for them. Reading billing, credits, limits, payments and documents works with a company token whose role holds billing.view.

Amount arguments and flags are dollars (1000, 19.99). Purchases and the auto-reload threshold and amount must be whole dollars.

Spend limits: AI limits stop new AI work once reached; orders and hosting limits only notify; Studios limits are recorded and notified but not enforced. Turning --auto-reload on accepts the reload authorization it prints.

usage record needs billing.create_usage and a company admin's or the company's own token; Droplet tokens are refused, and Mist AI usage is reported through Mist instead.

Setting up a new card or bank account needs the browser flow in the admin; fluid billing instrument <bank-account-id> only switches back to a bank account whose ACH authorization was already given.