Investec Programmable Banking CLI

Deploy programmable card code, simulate transactions locally, and manage Investec accounts from the terminal. Binary name: ipb.

Community-maintained project aligned with the Investec Programmable Banking community. Not officially endorsed or supported by Investec—use and contribute with care.

Documentation map

This README follows Divio’s documentation system: pick the section that matches what you need.

| I want to… | Go to | |------------|--------| | Learn by doing (first successful flow) | Tutorials | | Solve a specific task | How-to guides | | Look up a command, flag, or error code | Reference | | Understand why the CLI works this way | Explanation | | Contribute or release | CONTRIBUTING.md |

Full option lists for every command: GENERATED_README.md (or run ipb <command> --help / ipb docs).

Tutorials

Learning-oriented: follow in order. You will install the CLI, save credentials, list a card, scaffold a project, simulate locally, deploy, and fetch logs.

Your first card flow

Time: about 10 minutes. You need: Node.js 24+ (or a standalone binary), Investec API credentials from the Developer Portal, and a programmable card.

1. Install

npm install -g investec-ipb
ipb --version

Other install methods: How to install.

2. Save credentials

Get your client ID, client secret, and API key from the API quick start guide.

ipb config --client-id <client-id> --client-secret <client-secret> --api-key <api-key>

Prefer credential files over putting secrets in environment variables. See Explanation: credentials and secrets.

3. List your cards

ipb cards

Note a card key for later steps (-c).

4. Scaffold a project

ipb new my-card-app
cd my-card-app

Optional templates: --template default or --template petro.

5. Simulate locally (no API keys required for this step)

Amount is in cents:

ipb run -f main.js -e prod --amount 60000 --currency ZAR --mcc 0000 \
  --merchant "Test Merchant" --city "Cape Town" --country ZA

6. Deploy to the card

deploy uploads (and can publish) code. You will be asked to confirm unless you pass --yes.

ipb deploy -f main.js -c <card-key>

7. Fetch execution logs

ipb logs -f executions.json -c <card-key>

You now have a working loop: edit → ipb run → ipb deploy → ipb logs. Next: How-to guides for profiles, env files, accounts, and automation.

How-to guides

Goal-oriented recipes. For every flag, use ipb <command> --help.

How to install

npm (recommended if you already use Node.js 24+):

npm install -g investec-ipb

On Windows PowerShell (if scripts are blocked):

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

Homebrew (standalone binary, no Node.js):

brew tap devinpearson/ipb
brew install ipb

Direct download: binaries on GitHub Releases.

macOS:

# Apple Silicon
curl -L https://github.com/devinpearson/ipb/releases/download/v0.9.3/ipb-macos-arm64 -o ipb
chmod +x ipb
sudo mv ipb /usr/local/bin/

# Intel
curl -L https://github.com/devinpearson/ipb/releases/download/v0.9.3/ipb-macos-x64 -o ipb
chmod +x ipb
sudo mv ipb /usr/local/bin/

Linux (.deb):

wget https://github.com/devinpearson/ipb/releases/download/v0.9.3/ipb_0.9.3_amd64.deb
sudo dpkg -i ipb_0.9.3_amd64.deb
sudo apt-get install -f

Linux binary:

curl -L https://github.com/devinpearson/ipb/releases/download/v0.9.3/ipb-linux-x64 -o ipb
# or: ipb-linux-arm64
chmod +x ipb
sudo mv ipb /usr/local/bin/

Windows: download ipb-win-x64.exe, rename to ipb.exe, add to PATH.

More packaging options: DISTRIBUTION.md.

How to configure credentials and profiles

# Default credentials (~/.ipb/.credentials.json, mode 600)
ipb config --client-id <id> --client-secret <secret> --api-key <key>

# Optional card key / host — see ipb config --help
ipb config --card-key <card-key>

# Mauritius (MAU) credentials (separate from ZA PB/Card)
ipb config --mau-client-id <id> --mau-client-secret <secret> --mau-api-key <key>

# Named profiles
ipb config --profile production --client-id <id> --client-secret <secret> --api-key <key>
ipb config --profile staging --client-id <id> --client-secret <secret> --api-key <key>
ipb config profile set production
ipb config profile list
ipb config profile show

Use a profile on any command:

ipb cards --profile staging
ipb deploy --profile production -f main.js -c <card-key>
ipb mau accounts --profile production

How to use Mauritius (MAU) Open Banking

MAU uses the same OAuth shape as ZA APIs but separate credentials (mauClientId, mauClientSecret, mauApiKey, optional mauHost).

ipb mau accounts
ipb mau balances 5331
ipb mau transactions 5331 --from 2024-01-01 --to 2024-01-31
ipb mau documents 5331 --from 2025-01-01 --to 2025-01-31
ipb mau statement 5331 2025-01-31 --output statement.pdf

Edit in your editor (EDITOR, default nano / notepad.exe):

ipb config edit
ipb config edit --profile production

Custom credentials file:

ipb cards --credentials-file /path/to/credentials.json

How to deploy code and manage card environments

# One-shot deploy (upload + publish path; confirms by default)
ipb deploy -f main.js -e prod -c <card-key>
ipb deploy -f main.js -c <card-key> --yes

# Split steps
ipb upload -f main.js -c <card-key>
ipb publish -f main.js --code-id <code-id> -c <card-key>

# Environment variables on the card
ipb env -f env.json -c <card-key>
ipb upload-env -f env.json -c <card-key>

# Download code from the card
ipb fetch -f backup.js -c <card-key>
ipb published -f published.js -c <card-key>

Use .env.<name> locally and pass -e <name> when the command supports it (for example deploy / run).

How to simulate transactions

Local emulator (no Investec account required):

ipb run -f main.js -e prod --amount 60000 --currency ZAR --mcc 0000 \
  --merchant "Test Merchant" --city "Cape Town" --country ZA

Online simulator (uses API / card context and remote env):

ipb simulate -f main.js -c <card-key> --amount 60000 --currency ZAR --mcc 0000 \
  --merchant "Test Merchant" --city "Cape Town" --country ZA

Reference data for MCC / country / currency values:

ipb countries
ipb currencies
ipb merchants

How to enable or disable code on a card

ipb enable -c <card-key>
ipb disable -c <card-key>          # confirms
ipb disable -c <card-key> --yes

How to work with accounts and payments

ipb accounts
ipb balances <accountId>
ipb transactions <accountId>
ipb beneficiaries

Money movement requires confirmation (or --yes for automation):

ipb transfer <accountId> <beneficiaryAccountId> <amount> <reference>
ipb pay <accountId> <beneficiaryId> <amount> <reference>

Amounts for transfer/pay are in rands (for example 100.50), not cents.

How to install shell completion

Bash:

mkdir -p ~/.bash_completion.d
ipb completion bash > ~/.bash_completion.d/ipb
echo "source ~/.bash_completion.d/ipb" >> ~/.bashrc

Zsh:

mkdir -p ~/.zsh/completions
ipb completion zsh > ~/.zsh/completions/_ipb
# In ~/.zshrc:
# fpath=(~/.zsh/completions $fpath)
# autoload -U compinit && compinit

How to automate safely

# Machine-readable output
ipb cards --json
ipb accounts --json | jq .

# Skip confirms only when intentional
ipb deploy -f main.js -c <card-key> --yes

# Quiet / debug
ipb accounts --no-spinner
ipb accounts --verbose
# or: DEBUG=1 ipb accounts

When stdout is piped, the CLI favours structured output and turns spinners off. Destructive commands need --yes in non-interactive use.

Handle exit codes in scripts:

if ipb deploy -f main.js -c "$CARD" --yes; then
  echo "ok"
else
  echo "failed with exit $?"
fi

See Exit codes and Error codes.

Reference

Information-oriented lookup. Authoritative flags: ipb <command> --help or GENERATED_README.md.

Command map

| Command | Purpose | |---------|---------| | cards (c) | List programmable cards | | config (cfg) | Save credentials; profile / edit subcommands | | new | Scaffold a local project | | run (r) | Local transaction simulation | | simulate | Online simulator | | deploy (d) | Deploy code to a card | | upload (up) / publish (pub) | Upload or publish code | | fetch (f) / published | Download saved or published code | | env / upload-env | Card environment variables | | logs (log) | Execution logs | | enable / disable | Toggle code on a card | | accounts (acc) / balances (bal) / transactions (tx) | Account data (ZA PB) | | mau | Mauritius Open Banking (accounts, balances, transactions, documents, statement) | | beneficiaries / transfer / pay | Beneficiaries and payments | | countries / currencies / merchants | Reference data | | completion / docs / env-list | Shell completion, docs dump, env catalogue |

These commands are disabled and return an error: ai, bank, register, login.

Shared options (most API commands)

• Auth: --client-id, --client-secret, --api-key, --host, --credentials-file, --profile
• MAU auth: --mau-client-id, --mau-client-secret, --mau-api-key, --mau-host
• Output: --json, --yaml, --output <file>, -v / --verbose
• Spinner: --no-spinner (preferred); -s / --spinner is deprecated
• Destructive: --yes where supported

Environment variables

List everything the CLI documents:

ipb env-list
ipb env-list --json

Common categories:

• API: INVESTEC_HOST, INVESTEC_CLIENT_ID, INVESTEC_CLIENT_SECRET, INVESTEC_API_KEY, INVESTEC_CARD_KEY
• MAU API: INVESTEC_MAU_HOST, INVESTEC_MAU_CLIENT_ID, INVESTEC_MAU_CLIENT_SECRET, INVESTEC_MAU_API_KEY
• Behaviour: DEBUG, REJECT_UNAUTHORIZED, NO_COLOR, FORCE_COLOR, EDITOR, PAGER, TMPDIR, IPB_NO_UPDATE_CHECK

Exit codes

| Exit | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Validation / bad input | | 3 | Authentication | | 4 | File | | 5 | API (includes rate limits) | | 6 | Network | | 7 | Permission |

Error codes

Messages look like Error (E####): ….

| Code | Description | |------|-------------| | E4002 | Missing API token | | E4003 | Missing card key | | E4004 | Missing environment file | | E4005 | Invalid credentials | | E4007 | Template not found | | E4008 | Invalid project name | | E4009 | Project exists | | E4010 | File not found | | E4012 | Missing account ID | | E4014 | Rate limit exceeded | | E4019 | Unsupported operation | | E4020 | Missing or invalid date range (MAU --from / --to) | | E5001 | Deploy / API operation failed |

Quick fixes: missing card key → ipb cards then -c; bad auth → ipb config; missing .env.<env> → create the file or change -e.

Explanation

Understanding-oriented background. Skip this until you care about the “why”.

Credentials and secrets

Credential files under ~/.ipb/ use owner-only permissions (600) and atomic writes. Environment variables are convenient but can leak via process lists, CI logs, and shell history. The CLI may warn when secrets appear in the environment (especially with --verbose / DEBUG or in CI). Prefer ipb config and profiles for day-to-day use.

Resolution order (highest wins):

1. Command-line options (--api-key, …)
2. --profile or the active profile
3. Environment variables
4. Default credentials file (~/.ipb/.credentials.json)

Destructive operations and --yes

deploy, publish, disable, transfer, and pay change live card state or move money. Interactive runs ask for confirmation. Automation and pipes should pass --yes only when the action is intentional.

Local run vs online simulate

• run uses the local emulator and local files/env—good for fast iteration offline.
• simulate hits Investec’s online simulator with your card/API context—closer to production behaviour, needs credentials.

Agent / automation tip

Copyable skill for AI agents that operate ipb: skills/ipb/. Prefer --json and confirm money or deploy steps before running them.

Contributing and development

Issues and pull requests are welcome. For running locally, tests, docs, version bumps, and releases, see CONTRIBUTING.md.

git clone https://github.com/devinpearson/ipb.git
cd ipb
npm install
npm run build
node bin/index.js --help

License

MIT — see LICENSE.md.

Contact

Open a GitHub issue for questions and bugs.

Acknowledgments

• Commander, Chalk, Ora, VHS
• CLIG.dev, Node.js CLI Apps Best Practices
• Investec Programmable Banking Community
• Divio documentation system

Related projects

• Banking API Simulator
• Random Banking Data Generator
• Open Banking POS
• Card Issuer
• Blockly editor for card code
• HTTP server for card emulator
• Card code emulator package