servosity/msp-skills/maxio

Maxio - Claude Code Skill

Prerequisites: Install the CLI

This skill drives the maxio-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

``bash bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/maxio/install.sh) ``

1. Windows (PowerShell):

``powershell iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/maxio/install.ps1 | iex ``

1. Verify: maxio-cli --version
2. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the maxio-cli and maxio-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Every Maxio Advanced Billing resource is queryable offline, but the point is the revenue math no other tool computes: the five-bucket MRR movement waterfall, NRR/GRR/quick-ratio, per-client recurring-revenue history, and a 'what needs attention' triage rollup. It snapshots each sync into a local time series, so historic cohort and retention curves accrue even though the live API has no endpoint to reconstruct them after the fact. Reads are the safe default; mutating commands execute only when you invoke them.

When to Use This CLI

Use this CLI when an agent or operator needs Maxio recurring-revenue intelligence from the terminal: current and historic MRR/ARR, the movement waterfall, retention and churn, per-client revenue, and a revenue triage list. It is the right tool when the answer requires joining or trending data across subscriptions, customers, components, and invoices, or when the Maxio dashboard is too slow/manual to query.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI for GAAP recognized revenue, ASC 606, or deferred-revenue schedules - those live in SaaS Optics, a separate Maxio API not covered by this build.
• Do not point an autonomous agent at create, cancel, refund, or modify operations against production without a human in the loop - these are real writes that execute when invoked; preview them with --dry-run and require approval (see governance.md).
• Do not use it for payment processing, collections, or dunning actions.

Unique Capabilities

History the live API can't reconstruct

• `mrr waterfall` - See MRR move month over month, broken into New, Expansion, Contraction, Churn, and Reactivation - plus ARR and growth rate.

_Reach for this when an agent needs the recurring-revenue movement breakdown for a period instead of a single point-in-time number._

``bash maxio-cli mrr waterfall --since 2026-01-01 --group-by month --agent ``

• `mrr client` - Normalized MRR for one customer or the whole book, with the history the live API has no endpoint for.

_Use this to answer 'what is recurring revenue for this account, and how has it trended' without scraping the dashboard._

``bash maxio-cli mrr client --customer 1234567 --since 2025-01-01 --agent ``

• `retention` - Net and gross revenue retention, logo churn, revenue churn, and quick ratio over any window.

_Pick this when the question is about retention ratios over time rather than the raw movement dollars._

``bash maxio-cli retention --since 2025-01-01 --group-by month --agent ``

• `cohort` - Revenue and logo retention by signup-month cohort across N periods.

_Use for cohort analysis; depth grows as the local snapshot history accumulates across syncs._

``bash maxio-cli cohort --by signup-month --periods 12 --agent ``

• `mrr now` - Current MRR + ARR + growth vs the prior snapshot.

_Use this for the one-line answer to 'what is our MRR right now and is it growing'._

``bash maxio-cli mrr now --json ``

• `mrr sync` - Snapshot current MRR and backfill movement history into the local store.

_Run it alongside sync so the revenue commands have snapshots and movements to compute on._

``bash maxio-cli mrr sync ``

Agent-native revenue ops

• `triage` - A ranked list of accounts that need attention: past-due, large upcoming renewals, and high-value concentration.

_Reach for this to answer 'what revenue needs my attention this week' in one call instead of fanning out across endpoints._

``bash maxio-cli triage --limit 20 --agent ``

• `reconcile` - Per-customer gaps between normalized MRR and the amounts actually invoiced, with the deltas flagged.

_Use this to catch where normalized recurring revenue and invoiced amounts diverge (discounts, usage spikes, proration)._

``bash maxio-cli reconcile --since 2026-01-01 --agent ``

• `usage-drivers` - Which metered/usage components drove expansion versus contraction MRR, ranked.

_Pick this when expansion or contraction needs to be attributed to specific usage-billed components._

``bash maxio-cli usage-drivers --since 2026-01-01 --limit 20 --agent ``

• `arpa` - ARPA/ARPU, MRR percentiles, and price-vs-volume decomposition of MRR change.

_Pick this when the question is whether revenue moved because of price or because of customer count._

``bash maxio-cli arpa --json ``

• `churn` - Logo and revenue churn per period, voluntary vs involuntary, by reason code.

_Use this to see who churned, why, and how much recurring revenue left with them._

``bash maxio-cli churn --since 2026-01-01 --json ``

• `concentration` - Customer concentration: share of ARR held by the top 1 / 5 / 10 customers.

_Reach for this when the question is how dependent revenue is on a handful of accounts._

``bash maxio-cli concentration --limit 20 --json ``

• `new-customers` - New logos acquired per period (first-activation month) plus the new MRR they brought.

_Use this to answer how many new accounts were won per month and what they added._

``bash maxio-cli new-customers --since 2026-01-01 --json ``

• `renewals` - Active subscriptions renewing within the next N days (default 90), with MRR at risk.

_Pick this to see which renewals are coming up and how much recurring revenue rides on them._

``bash maxio-cli renewals --within 30 --json ``

• `revenue-mix` - Recurring vs usage vs services split of the latest month's billed line items.

_Use this when the question is how much of billed revenue is recurring versus usage or services._

``bash maxio-cli revenue-mix --month 2026-05 --json ``

Command Reference

api-exports - Manage api exports

• maxio-cli api-exports export-invoices - This API creates an invoices export and returns a batchjob object.
• maxio-cli api-exports export-proforma-invoices - This API creates a proforma invoices export and returns a batchjob object.
• maxio-cli api-exports export-subscriptions - This API creates a subscriptions export and returns a batchjob object.
• maxio-cli api-exports list-exported-invoices - This API returns an array of exported invoices for a provided batch_id.
• maxio-cli api-exports list-exported-proforma-invoices - This API returns an array of exported proforma invoices for a provided batch_id.
• maxio-cli api-exports list-exported-subscriptions - This API returns an array of exported subscriptions for a provided batch_id.
• maxio-cli api-exports read-invoices-export - This API returns a batchjob object for invoices export.
• maxio-cli api-exports read-proforma-invoices-export - This API returns a batchjob object for proforma invoices export.
• maxio-cli api-exports read-subscriptions-export - This API returns a batchjob object for subscriptions export.

bank-accounts - Manage bank accounts

chargify-js-keys-json - Manage chargify js keys json

• maxio-cli chargify-js-keys-json - Returns public keys used for Maxio.js (formerly Chargify.js).

components - Manage components

• maxio-cli components find - This request will return information regarding a component having the handle you provide.
• maxio-cli components update - This request will update a component. You may read the component by either the component's id or handle.

components-json - Manage components json

• maxio-cli components-json - This request will return a list of components for a site.

components-price-points-json - Manage components price points json

• maxio-cli components-price-points-json - This method allows to retrieve a list of Components Price Points belonging to a Site.

coupons - Manage coupons

• maxio-cli coupons find - You can search for a coupon via the API with the find method.
• maxio-cli coupons validate - You can verify if a specific coupon code is valid using the validate method.

coupons-json - Manage coupons json

• maxio-cli coupons-json - You can retrieve a list of coupons.

credit-notes - Manage credit notes

• maxio-cli credit-notes <uid> - Use this endpoint to retrieve the details for a credit note.

credit-notes-json - Manage credit notes json

• maxio-cli credit-notes-json - Credit Notes are like inverse invoices. They reduce the amount a customer owes.

customers - Manage customers

• maxio-cli customers delete - This method allows you to delete the Customer.
• maxio-cli customers read - Retrieves the Customer properties by Advanced Billing-generated Customer ID.
• maxio-cli customers read-by-reference - Use this method to return the customer object if you have the unique Reference ID (Your App) value handy.
• maxio-cli customers update - This method allows to update the Customer.

customers-json - Manage customers json

• maxio-cli customers-json create-customer - You may create a new Customer at any time, or you may create a Customer at the same time you create a Subscription.
• maxio-cli customers-json list-customers - This request will by default list all customers associated with your Site.

endpoints - Manage endpoints

• maxio-cli endpoints <endpoint_id> - Updates an Endpoint.

endpoints-json - Manage endpoints json

• maxio-cli endpoints-json create-endpoint - Creates an endpoint and assigns a list of webhook subscriptions (events) to it.
• maxio-cli endpoints-json list-endpoints - Returns created endpoints for a site.

event-based-billing - Manage event based billing

• maxio-cli event-based-billing activate-event-based-component - Activates an event-based component for a single subscription.
• maxio-cli event-based-billing deactivate-event-based-component - Deactivates an event-based component for a single subscription.

events - Manage events

• maxio-cli events read-count - Get a count of all the events for a given site by using this method.
• maxio-cli events record - Records a single event for Events-Based Billing.

events-json - Manage events json

• maxio-cli events-json - Advanced Billing Events include various activity that happens around a Site.

invoices - Manage invoices

• maxio-cli invoices list-events - This endpoint returns a list of invoice events.
• maxio-cli invoices read - Use this endpoint to retrieve the details for an invoice.
• maxio-cli invoices record-payment-for-multiple - This API call should be used when you want to record an external payment against multiple invoices.

invoices-json - Manage invoices json

• maxio-cli invoices-json - By default, invoices returned on the index will only include totals, not detailed breakdowns for line_items