Set Up the CLI
The fob-txn command lets you list accounts, inspect transactions, and export data from your terminal. Start with a connected mailbox if you want imported transactions to explore.
1. Install Node.js and the CLI
Install the current LTS release from the official Node.js download page. It includes npm, the package installer used below. After installing, open Terminal on macOS/Linux or PowerShell on Windows.
Check that both commands work:
node --version
npm --version
Install the Transactions CLI and check its help:
npm install -g @finopsbricks/fob-txn
fob-txn --help
If node, npm, or fob-txn is not found, reopen your terminal. If it still fails, check that Node.js and npm's global executable directory are on your PATH. An npm permission error means your global install directory is not writable; use a Node.js installation managed by your user account or ask your computer administrator to fix the installation permissions.
2. Create an API key
- In Transactions, select the same organization as your mailbox.
- Go to Settings → API keys and select Create new API Key.
- Give it a recognizable name, such as
My laptop. - Choose Read Only permissions for the commands in this guide, then select Create API Key.
- Copy both the Key and Secret. Save the secret securely now; it is only shown at creation.
The CLI uses this key and secret to access that organization. Your email app password belongs only in the mailbox connection form. See API authentication for permission details.
3. Add and select a profile
A profile is a named set of credentials. Replace the two placeholder values below with the key and secret you just copied. myorg is a local name you choose, not an organization ID.
fob-txn config profiles add myorg --api-key 'YOUR_API_KEY' --api-secret 'YOUR_API_SECRET'
fob-txn config profiles use myorg
fob-txn whoami
The API URL defaults to https://txn.finopsbricks.com. whoami should return your organization ID, organization name, API key name, and scopes. Saving a profile alone does not prove the credentials work; check whoami before continuing.
Credentials are saved in ~/.fob/fob-txn/config.yml. Keep this file private. Commands containing secrets can also remain in shell history; follow your terminal's history-removal procedure after setup and do not share the command or config file.
4. Read and export transactions
fob-txn accounts list
fob-txn transactions list --limit 5
fob-txn transactions list --from 2026-09-01 --to 2026-09-14
Replace the dates with the period you want to inspect. To filter by account, copy an ID from accounts list and replace ACCOUNT_ID:
fob-txn accounts show ACCOUNT_ID
fob-txn transactions list --account ACCOUNT_ID
List commands return one page by default. Use --all to fetch all pages, up to the CLI's 15,000-row cap; narrow the date range for larger exports.
fob-txn transactions list --all --format csv --output transactions.csv
fob-txn transactions list --limit 5 --json
The table display shows decimal amounts. JSON returns raw amounts scaled by 1,000: for example, 1234500 represents 1234.50 in the account's currency.
Switch organizations
Create a separate API key in each organization and add it under another profile name. Then select it with fob-txn config profiles use, or choose a profile for one command:
fob-txn config profiles list
fob-txn --profile myorg transactions list --limit 5
Troubleshoot the CLI
| What you see | What to do |
|---|---|
| No credentials / no active profile | Add a profile, then run fob-txn config profiles use myorg. |
401 UNAUTHORIZED | Check that the key and secret are a matching pair and that the key has not been deleted. Run the profile-add command again with the correct pair, then retry whoami. |
403 FORBIDDEN | Check the key's permissions. Account and transaction lists need Read access to their respective resources. |
| Wrong organization | Run fob-txn config profiles list, select the intended profile, and check whoami. |
| No transactions | Verify the organization, remove date/account filters, and check Parsed Emails and mailbox status in the app. Importing may still be in progress. |
| Network or server error | Check internet access and retry. If it persists, report the error without including your credentials. |
For more options, run fob-txn transactions list --help or fob-txn getting-started.