Install and Use the Maxio CLI

The Maxio CLI is a maxio command you run from a terminal or a script. It talks to Maxio through a connector you already have, so a command works exactly when that connector's permissions allow it, and it covers Advanced Billing, Maxio Core, Sales Order, and metering in one tool instead of a separate integration for each.

Before you start

A few things need to be true before you install anything.

• You need an existing connector with API access. The CLI uses the same connector and permissions as any other API integration, so set one up first if you have not already.
• You need to be able to view the connector's credentials. The CLI tab described below appears only for connectors that use an API key, and only for people who can view that connector's credentials.
• You run the install command on whatever computer or server should reach Maxio, such as your laptop, a CI runner, or a scheduled job host.

Step 1: Get the install and connect commands

Every connector that supports the CLI has a CLI tab on its connector details page with the exact commands for that connector, including its address and API key already filled in.

To find your commands

1. Open the connector you want to use from a terminal.
2. Select the CLI tab.
3. Use the Copy button next to each command rather than selecting the text manually. The API key shown on the page is shortened for display, but Copy puts the full key on your clipboard.

Step 2: Install the CLI

Run the install command for your operating system. It downloads the maxio program, checks it against a published checksum, and installs it. On Windows, it also adds the program to your PATH. On macOS and Linux, it installs to ~/.local/bin, and if that folder is not on your PATH, the command prints the line to add it. Running the same command again later updates it: there is no separate update command.

On macOS or Linux, run this command in a terminal:

curl -fsSL https://<install-address>/cli/install.sh | sh

On Windows, run this command in PowerShell:

irm https://<install-address>/cli/install.ps1 | iex

Step 3: Connect your connector

Run this command to save your connector on this computer. It stores the connector's address and API key under the name you choose, so later commands can use them without you entering them again:

maxio connector add <connector-name> --url <connector-address> --token <api-key>

The command on your connector's CLI tab already has <connector-name>, <connector-address>, and <api-key> filled in, so copy it as it is rather than typing your own values. Paste it only into a terminal you trust. The copied command includes the full API key, so it is saved in your shell history. To keep the key out of your history, run this command instead. The CLI asks you to paste the API key, and the key stays hidden as you type:

maxio connector add <connector-name> --url <connector-address> --token-stdin

If you manage more than one connector, repeat this step for each one and add --connector <name> to a command to pick which one it runs against; otherwise the CLI uses whichever connector you added first.

Step 4: Check it works

Run this command to confirm that the CLI can reach Maxio with the connector you just saved.

maxio whoami

This asks Maxio who the saved key belongs to. When the connection is good, it shows your organization name, the connector name, and a connected status. If it prints an error instead, go back to your connector's CLI tab and run the connect command again.

Step 5: Run a command

Commands follow the shape maxio <backend> <resource> <verb>, where backend is billing (Advanced Billing), core (Maxio Core), sales (Sales Order), or metering.

These examples list open invoices, list Maxio Core customers, and show one invoice:

maxio billing invoices list --status open --limit 50
maxio core customers list
maxio billing invoices get inv_8gd

maxio commands lists every command your connector's permissions currently allow, so it's a quick way to see what you can do without reading the full reference. Add --help to any command to see its full set of options, for example maxio billing invoices list --help.

A command that your connector is not permitted to run fails with a message naming the missing permission, rather than running partway. The CLI keeps a saved copy of your connector's permissions for up to 15 minutes. If you were just given a new permission, you do not need to reconnect: add --refresh to a command to load the current permissions right away, or wait for the saved copy to expire.

Step 6: Make changes

Creating, updating, or deleting something is a write, and every write needs an explicit --yes flag:

maxio billing invoices void inv_8gd --body '{"void":{"reason":"duplicate"}}' --yes

Leaving off --yes does not run the write: the CLI stops and tells you to add it. Add --dry-run instead to see exactly what would be sent (method, address, and body) without sending anything, which is a safe way to check a command before running it for real. Deletes and actions like voiding or canceling are called out as impossible to undo, since there is no confirmation prompt beyond --yes.

Card numbers and bank account details are never shown in full in --dry-run or troubleshooting output, even though the real request still carries them.

Step 7: Read results

By default, results print as readable tables and summaries in your terminal. Add --output json when you want to feed the result into another program or script instead. When the CLI runs in a CI job or under a coding agent, it prints JSON by default.

A list that can have many results, such as invoices or customers, only fetches one page at a time unless you add --all, which keeps fetching until there is nothing left. It stops after 50 pages by default, and if more results exist, it tells you which page to continue from. Add --max-pages to raise that limit.

Optional: set up your coding agent

If you use Claude Code or Codex, your connector's CLI tab has an optional command that installs a Maxio skill for it, so you can ask your coding agent for invoices, customers, or other Maxio data in plain language instead of writing maxio commands yourself:

maxio ai setup-all

Related information

For setting up the connector the CLI uses, see Configure the Maxio MCP Connector, which covers the same connector and permissions concepts.