@x-money/cli
xmoney, the X Money API from a terminal. Create checkout sessions, charge linked accounts, issue refunds and payouts, and read anything the API exposes.
Every command is a thin wrapper over @x-money/core, so the two cannot drift apart about what the API offers.
Node 24 or newer.
npm install -g @x-money/cli
xmoney --help
Or run it without installing: npx @x-money/cli --help.
Quick start
xmoney login # prompts for a key, stores it on the default profile
xmoney whoami # shows which key and base url resolved, key masked
xmoney payments list --limit 10
Credentials
A key is looked for in three places, in order: --api-key, then XMONEY_API_KEY, then the profile on disk. The base url resolves the same way through --base-url and XMONEY_API_BASE_URL, falling back to the profile and then to the SDK default.
Profiles keep keys apart, for example a test-mode key beside a live one. --profile or XMONEY_PROFILE selects one, and the default is named default.
xmoney login --profile test # prompts for your xmsk_test_ key
xmoney payments list --profile test
The config file lives at $XDG_CONFIG_HOME/xmoney/config.json, or ~/.config/xmoney/config.json when that is unset. It holds secret keys, so it is written 0600 inside a 0700 directory, and an existing file is tightened to 0600 on every write.
Commands
| Resource | Actions |
|---|---|
checkouts | create, get |
exchanges | create, get |
accounts | get, list, revoke |
customers | get, list |
payments | create, get, list, capture, release-authorization, update-authorization |
refunds | create, get, list |
payouts | create, get, list, reverse |
settlements | list, get, file |
Plus login and whoami. xmoney --help prints the full flag reference, and --help works on any command.
This table is checked against the methods @x-money/core exposes, in both directions, so a resource cannot reach the SDK without a command shipping here in the same release.
Creating things
Each create takes typed flags, listed under xmoney --help. Anything they do not cover goes through --data as raw JSON, and --metadata k=v repeats.
xmoney refunds create --payment <payment-id> --amount 500 --reference refund-order-8471
xmoney payouts create --data '{"account_id":"xmac_...","amount":2500}'
Amounts are integers in the currency's smallest unit, so 49999 is $499.99.
Every POST carries a generated idempotency key. Pass --idempotency-key to make a retry safe across invocations, which is what you want when a command is driven by an order id.
With a test key, --test-outcome sends the Xm-Test-Outcome header to force a decline, an expiry, or an authorization error, for example --test-outcome INSUFFICIENT_FUNDS.
Pagination
Lists return one page. --all follows the cursor to the end and returns the accumulated set, so it is a request per page and worth a thought on large accounts.
xmoney payouts list --limit 100 --all
Output and exit codes
Results are JSON on stdout and nothing else, so | jq works. Everything else, prompts and errors included, goes to stderr.
--verbose adds one stderr line per request with its method, path, status, and x-request-id, so a call that succeeded but returned something surprising still leaves an id to quote.
| Exit | Meaning |
|---|---|
0 | Success. |
1 | The API returned an error. The error object, with its code, status, and request_id, is printed to stderr as JSON. |
2 | The request never got a response: network failure, timeout, or abort. |
64 | The command line or the credentials were wrong: a missing flag, or a key that is not a secret key. Nothing was sent. |
Every error the SDK can raise maps to one of these. A stack trace means a bug in the CLI itself.
Documentation
Guides, the API reference, and the webhook catalog are at xmoney.mintlify.site/docs.
Support
Report bugs and ask questions through the X Help Center. Security issues go through the same form; please do not post them publicly.
License
MIT. The full text ships in the package as LICENSE.