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):

Command-line options (--api-key, …)
--profile or the active profile
Environment variables
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

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github		.github
.husky		.husky
Formula		Formula
assets		assets
scripts		scripts
skills/ipb		skills/ipb
snap		snap
src		src
tapes		tapes
templates		templates
test		test
.biomeignore		.biomeignore
.cursorrules		.cursorrules
.gitignore		.gitignore
.markdownlint-cli2.yaml		.markdownlint-cli2.yaml
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
CI_CD_EXAMPLES.md		CI_CD_EXAMPLES.md
CONTRIBUTING.md		CONTRIBUTING.md
DISTRIBUTION.md		DISTRIBUTION.md
GENERATED_README.md		GENERATED_README.md
IMPROVEMENT_PLAN.md		IMPROVEMENT_PLAN.md
LICENSE		LICENSE
README.md		README.md
UBUNTU_DISTRIBUTION.md		UBUNTU_DISTRIBUTION.md
biome.json		biome.json
esbuild.config.js		esbuild.config.js
instructions.txt		instructions.txt
package-lock.json		package-lock.json
package.json		package.json
pkg.config.json		pkg.config.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

Investec Programmable Banking CLI

Documentation map

Tutorials

Your first card flow

1. Install

2. Save credentials

3. List your cards

4. Scaffold a project

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

6. Deploy to the card

7. Fetch execution logs

How-to guides

How to install

How to configure credentials and profiles

How to use Mauritius (MAU) Open Banking

How to deploy code and manage card environments

How to simulate transactions

How to enable or disable code on a card

How to work with accounts and payments

How to install shell completion

How to automate safely

Reference

Command map

Shared options (most API commands)

Environment variables

Exit codes

Error codes

Explanation

Credentials and secrets

Destructive operations and --yes

Local run vs online simulate

Agent / automation tip

Contributing and development

License

Contact

Acknowledgments

Related projects

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages

Destructive operations and `--yes`

Local `run` vs online `simulate`