| name | maxio |
| description | Open, local revenue-intelligence CLI for Maxio Advanced Billing - MRR waterfalls, retention, and per-client history computed offline from a SQLite mirror, so the trended history survives even though the live API returns only point-in-time figures. Trigger phrases: `what's our MRR`, `show the MRR waterfall`, `recurring revenue for this customer`, `net revenue retention this year`, `what revenue needs attention`, `use maxio`, `run maxio`. |
| author | Damien Stevens |
| license | Apache-2.0 |
| vendor | Maxio |
| argument-hint | <command> [args] | install cli|mcp |
| allowed-tools | Read Bash |
| metadata | {"openclaw":{"requires":{"bins":["maxio-cli"]},"install":[{"kind":"go","bins":["maxio-cli"],"module":"github.com/mvanhorn/printing-press-library/library/payments/maxio/cmd/maxio-cli"}]}} |
Maxio - Printing Press CLI
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:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:
npx -y @mvanhorn/printing-press-library install maxio --cli-only
- Verify:
maxio-cli --version
- Ensure the reported install directory is on
$PATH for the agent/runtime that will invoke this skill.
If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.4 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:
go install github.com/mvanhorn/printing-press-library/library/payments/maxio/cmd/maxio-cli@latest
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
These capabilities aren't available in any other tool for this API.
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.
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.
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.
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.
maxio-cli cohort --by signup-month --periods 12 --agent
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.
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).
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.
maxio-cli usage-drivers --since 2026-01-01 --limit 20 --agent
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
mrr-json - Manage mrr json
maxio-cli mrr-json - This endpoint returns your site's current MRR, including plan and usage breakouts.
mrr-movements-json - Manage mrr movements json
maxio-cli mrr-movements-json - This endpoint returns your site's MRR movements.
offers - Manage offers
maxio-cli offers <offer_id> - This method allows you to list a specific offer's attributes.
offers-json - Manage offers json
maxio-cli offers-json create-offer - Create an offer within your Advanced Billing site by sending a POST request.maxio-cli offers-json list-offers - This endpoint will list offers for a site.
one-time-tokens - Manage one time tokens
maxio-cli one-time-tokens <chargify_token> - One Time Tokens aka Advanced Billing Tokens house the credit card or ACH (Authorize.
payment-profiles - Manage payment profiles
maxio-cli payment-profiles delete-unused - Deletes an unused payment profile.maxio-cli payment-profiles read - Using the GET method you can retrieve a Payment Profile identified by its unique ID.maxio-cli payment-profiles update - In the event that you are using the Authorize.
payment-profiles-json - Manage payment profiles json
maxio-cli payment-profiles-json create-payment-profile - Creates a payment profile for a customer.maxio-cli payment-profiles-json list-payment-profiles - This method will return all of the active payment_profiles for a Site, or for one Customer within a site.
portal - Manage portal
maxio-cli portal enable-billing-for-customer - Full documentation on how the Billing Portal operates within the Advanced Billing UI is available in the Maxio docs.maxio-cli portal read-billing-link - This method will provide to the API user the exact URL required for a subscriber to access the Billing Portal.maxio-cli portal resend-billing-invitation - You can resend a customer's Billing Portal invitation.maxio-cli portal revoke-billing-access - You can revoke a customer's Billing Portal invitation.
price-points - Manage price points
product-families - Manage product families
maxio-cli product-families <id> - Retrieves a Product Family via the product_family_id. The response will contain a Product Family object.
product-families-json - Manage product families json
maxio-cli product-families-json create-product-family - Creates a Product Family within your Advanced Billing site.maxio-cli product-families-json list-product-families - Retrieve a list of Product Families for a site.
product-price-points - Manage product price points
products - Manage products
maxio-cli products archive - Archives the product.maxio-cli products read - Reads the current details of a product.maxio-cli products read-by-handle - Retrieves a Product object by its api_handle.maxio-cli products update - Updates aspects of an existing product.
products-json - Manage products json
maxio-cli products-json - This method allows to retrieve a list of Products belonging to a Site.
products-price-points-json - Manage products price points json
maxio-cli products-price-points-json - This method allows retrieval of a list of Products Price Points belonging to a Site.
proforma-invoices - Manage proforma invoices
maxio-cli proforma-invoices <proforma_invoice_uid> - Use this endpoint to read the details of an existing proforma invoice.
reason-codes - Manage reason codes
maxio-cli reason-codes delete - This method gives a merchant the option to delete one reason code from the Churn Reason Codes.maxio-cli reason-codes read - This method gives a merchant the option to retrieve a list of a particular code for a given Site by providing themaxio-cli reason-codes update - This method gives a merchant the option to update an existing reason code for a given site.
reason-codes-json - Manage reason codes json
maxio-cli reason-codes-json create-reason-code - ReasonCodes are a way to gain a high level view of why your customers are cancelling the subscription to your productmaxio-cli reason-codes-json list-reason-codes - This method gives a merchant the option to retrieve a list of all of the current churn codes for a given site.
referral-codes - Manage referral codes
maxio-cli referral-codes - Use this method to determine if the referral code is valid and applicable within your Site.
sellers - Manage sellers
site-json - Manage site json
maxio-cli site-json - Retrieves site data. Full documentation on Sites in the Advanced Billing UI is available in the Maxio docs.
sites - Manage sites
maxio-cli sites - Clears all data from a test site asynchronously.
stats-json - Manage stats json
maxio-cli stats-json - The Stats API is a very basic view of some Site-level stats. This API call only answers with JSON responses.
subscription-groups - Manage subscription groups
maxio-cli subscription-groups delete - Deletes a subscription group. Only groups without members can be deleted.maxio-cli subscription-groups find - Finds the subscription group associated with a subscription.maxio-cli subscription-groups read - Returns subscription group details.maxio-cli subscription-groups signup-with - Creates multiple subscriptions at once under the same customer and consolidates them into a subscription group.maxio-cli subscription-groups update-members - Updates subscription group members.
subscription-groups-json - Manage subscription groups json
maxio-cli subscription-groups-json create-subscription-group - Creates a subscription group with given members.maxio-cli subscription-groups-json list-subscription-groups - Returns an array of subscription groups for the site.
subscriptions - Manage subscriptions
maxio-cli subscriptions cancel - Cancels the Subscription. The Delete method sets the Subscription state to canceled.maxio-cli subscriptions create-signup-proforma-invoice - This endpoint is only available for Relationship Invoicing sites.maxio-cli subscriptions find - Finds a subscription by its reference.maxio-cli subscriptions preview - Previews a subscription by POSTing the same JSON or XML as for a subscription creation.maxio-cli subscriptions preview-signup-proforma-invoice - This endpoint is only available for Relationship Invoicing sites.maxio-cli subscriptions read - Retrieves subscription details.maxio-cli subscriptions update - Updates one or more attributes of a subscription.
subscriptions-components-json - Manage subscriptions components json
maxio-cli subscriptions-components-json - Lists components applied to each subscription.
subscriptions-json - Manage subscriptions json
maxio-cli subscriptions-json create-subscription - Creates a Subscription for a customer and product. Specify the product with product_id or product_handle.maxio-cli subscriptions-json list-subscriptions - Returns an array of subscriptions from a Site.
subscriptions-mrr-json - Manage subscriptions mrr json
maxio-cli subscriptions-mrr-json - This endpoint returns your site's current MRR, including plan and usage breakouts split per subscription.
webhooks - Manage webhooks
maxio-cli webhooks enable - Enables webhooks for your site.maxio-cli webhooks replay - Replays webhooks. Posting to this endpoint does not immediately resend the webhooks.
webhooks-json - Manage webhooks json
maxio-cli webhooks-json - Retrieves a list of webhooks. You can pass query parameters if you want to filter webhooks.
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
maxio-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query.
Recipes
Board-prep MRR movement
maxio-cli mrr waterfall --since 2026-01-01 --group-by month --agent
The month-by-month New/Expansion/Contraction/Churn/Reactivation breakdown, agent-formatted for a deck.
Narrow a deeply-nested subscription pull
maxio-cli subscriptions-json list-subscriptions --agent --select subscription.product.name,subscription.state,subscription.current_period_ends_at
Use --agent with --select dotted paths so the agent reads only the fields it needs instead of the full nested subscription payload.
Find accounts that need attention
maxio-cli triage --limit 20 --agent
Ranked accounts that need attention: past-due, large upcoming renewals, and high-value concentration.
Reconcile one client's normalized vs billed
maxio-cli reconcile --customer 1234567 --since 2026-01-01 --agent
Per-customer gaps between normalized MRR and what was actually invoiced for that client.
Auth Setup
Maxio Advanced Billing uses HTTP Basic authentication. Set three environment variables: MAXIO_USERNAME, MAXIO_PASSWORD, and MAXIO_SITE (your subdomain, e.g. acme for acme.chargify.com). For Advanced Billing API-key access, MAXIO_USERNAME is your API key (Config -> Integrations -> API Keys) and MAXIO_PASSWORD is the literal value 'x'. Read commands are safe to run by default; mutating commands execute when you invoke them (some prompt for confirmation interactively, which --agent/--yes skips), so preview with --dry-run and approve writes per your agent policy.
Run maxio-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
-
Pipeable - JSON on stdout, errors on stderr
-
Filterable - --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
maxio-cli api-exports export-invoices --agent --select id,name,status
-
Previewable - --dry-run shows the request without sending
-
Offline-friendly - sync/search commands can use the local SQLite store when available
-
Non-interactive - never prompts, every input is a flag
-
Explicit retries - use --idempotent only when an already-existing create should count as success, and --ignore-missing only when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
maxio-cli feedback "the --since flag is inclusive but docs say exclusive"
maxio-cli feedback --stdin < notes.txt
maxio-cli feedback list --json --limit 10
Entries are stored locally at ~/.local/share/maxio-cli/feedback.jsonl. They are never POSTed unless MAXIO_FEEDBACK_ENDPOINT is set AND either --send is passed or MAXIO_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|
stdout | Default; write to stdout only |
file:<path> | Atomically write output to <path> (tmp + rename) |
webhook:<url> | POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration.
maxio-cli profile save briefing --json
maxio-cli --profile briefing api-exports export-invoices
maxio-cli profile list --json
maxio-cli profile show briefing
maxio-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or --help → show maxio-cli --help output
- Starts with
install → ends with mcp → MCP installation; otherwise → see Prerequisites above
- Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
- Install the MCP server:
go install github.com/mvanhorn/printing-press-library/library/payments/maxio/cmd/maxio-mcp@latest
- Register with Claude Code:
claude mcp add maxio-mcp -- maxio-mcp
- Verify:
claude mcp list
Direct Use
- Check if installed:
which maxio-cli
If not found, offer to install (see Prerequisites at the top of this skill).
- Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agent flag:
maxio-cli <command> [subcommand] [args] --agent
- If ambiguous, drill into subcommand help:
maxio-cli <command> --help.
