Advanced usage

Everything here is the CLI doing work you would otherwise do by hand: proving a deploy is healthy, producing a report, or telling you which of seven possible things is broken.

In a pipeline

There is no browser in CI, so the key comes from the environment. Every command reads WAJUB_API_KEY, and when it is set it wins over any profile, --profile included.

#!/usr/bin/env bash
set -euo pipefail

export WAJUB_API_KEY="$WAJUB_SANDBOX_KEY"   # from your CI secret store

# Fail the job if the key, the network or the account is wrong
wajub doctor --json > doctor.json

# Fail the job if the webhook endpoint disappeared
wajub webhooks list --json \
  | jq -e '.items[] | select(.url == "https://example.com/webhooks/wajub")' > /dev/null

--json on every command makes the output parseable, and jq -e turns "no match" into a non zero exit status, which is what makes the step actually fail.

Exit codes and runs without a terminal

A step fails on the exit status, so here is what the CLI returns.

A pipeline has no terminal, so the CLI cannot ask anything there. A command that would ask for confirmation (a deletion, a payment, transfer or refund with a live key, wajub logout) fails with status 1 unless you pass --yes. wajub skills install needs --scope. A hidden prompt for a key (wajub config set, wajub login --manual) fails too: set WAJUB_API_KEY instead.

Reports from the terminal

The list commands plus jq replace a lot of small scripts.

# Yesterday's failures, with the reason
wajub payments list --status failed -f date_from=2026-01-14 -f date_to=2026-01-14 -f per_page=100 --json \
  | jq -r '.items[] | [.created_at, .id, .amount, .currency, .failure_reason] | @tsv'

# Payouts still not settled
wajub transfers list --status processing --json \
  | jq -r '.items[] | [.id, .amount, .currency, .created_at] | @tsv'

--since and --until are not read by the API, so the dates go through -f date_from and -f date_to, which only payments, refunds and disputes accept. They are whole calendar days: for a shorter window, filter the timestamps in jq after listing the day.

Environment variables

Every variable below applies to every command, and a flag on the command line still wins over it, except for the key.

Shell completion

wajub completion install

TAB then completes commands, flags and their values: the statuses --status accepts on each list command, event types and payment.* wildcards for wajub listen --events (one after the other, comma-separated), wajub trigger events, your profiles for --profile and wajub config use, and API paths for wajub get, post and delete. It works in bash (3.2 and later, the one macOS ships included), zsh, fish and PowerShell.

The command detects your shell, or takes --shell bash|zsh|fish|powershell. It adds one block, between # >>> wajub completion >>> markers, to ~/.zshrc, ~/.bashrc (~/.bash_profile on macOS) or $PROFILE; for fish it writes ~/.config/fish/completions/wajub.fish. Open a new terminal, and that is all: the scripts are regenerated by the first command after each upgrade, so completion always matches the version installed.

wajub completion            # which shells have it, and where
wajub completion zsh        # the lines to add yourself, if you keep your dotfiles by hand
wajub completion uninstall  # removes the block, the fish file and the scripts

Before 1.7, wajub autocomplete set completion up differently. Those setups keep working after the upgrade, now with the new completion; wajub completion install replaces their line in your startup file.

Starting from a working example

$ wajub samples --list

Available samples:
  webhooks               Minimal webhook receiver with signature verification (Node.js, no dependencies)

$ wajub samples webhooks my-receiver

The webhook sample is deliberately dependency free, so you can read the whole verification in one file rather than through a framework.

Jumping to the Dashboard

wajub open              # the dashboard home
wajub open payments
wajub open keys

The pages it knows are balance, customers, dashboard, disputes, keys, payments, refunds, settings, transfers and webhooks.

When something is wrong

Three commands, in increasing order of how much they tell you.

$ wajub version
@wajub/cli/1.7.3 darwin-arm64 node-v22.11.0

$ wajub status
● Wajub API is reachable, https://api.wajub.com (HTTP 200)

$ wajub doctor
Wajub CLI diagnostics
  …seven checks, in order

status answers "is it them or me" and needs no credentials. doctor answers "which of my seven things is broken" and ends with a request id to hand to support.

An unknown command fails clearly rather than doing something surprising.

$ wajub payment

 ›   Error: "payment" is not a wajub command. Run `wajub help` for the list.

Telling us what is missing

wajub feedback

It opens the feedback form in your browser. Pair it with the request id from wajub doctor and the first two messages of a support thread are already answered.