Start here

Use the CLI

Before you begin

The Vantage CLI has two roles: agent for requesting access and reading transactions, and human for managing your accounts and permissions. This guide starts with the agent workflow.

A Vantage repository checkout, Node 22.13 or later and pnpm.

pnpm install --frozen-lockfile
export VANTAGE_API_URL=https://vantage.ailuminare.ca

Run from the repository root. The exported API URL applies to the commands in this terminal.

To explore the available commands, run:

pnpm --silent vantage
pnpm --silent vantage agent --help
pnpm --silent vantage human --help

Data commands return JSON. --silent keeps pnpm’s startup output out of the response. Failures exit nonzero and write error JSON to stderr; help commands print text.

The commands below use the hosted API selected above. Saved credentials are bound to the API origin where they were created. Use separate configuration files when switching deployments.

Register and request access

pnpm --silent vantage agent register --name 'Budget assistant' --runtime-label 'Codex' --hours 1 --purpose 'Explain last week spending' --requested-account-hint 'Amex'
pnpm --silent vantage agent status

The response includes an approval URL, valid for 15 minutes. The installation key is saved privately. Share the link with the account owner and wait for approval before reading transactions.

After approval, list the accounts and grants, then read a transaction page:

pnpm --silent vantage agent accounts
pnpm --silent vantage agent grants
pnpm --silent vantage agent transactions --grant-id GRANT_UUID --account-id ACCOUNT_UUID --limit 50

Replace GRANT_UUID and ACCOUNT_UUID with approved IDs. Accounts return a grantIds array; select a current grant from it.

The response contains a transaction page and nextCursor. Continue with the same grant and filters until nextCursor is null before calculating a total.

To request access again, reuse the installation with agent request:

pnpm --silent vantage agent request --hours 0.5 --purpose 'Review card spending' --requested-account-hint 'Amex'

--hours 0.5 requests thirty minutes. Durations support whole-minute precision from one minute to twelve hours.

The new request replaces any earlier pending link and requires human approval, including after a denied request or expired grant.

Manage access as a human

pnpm --silent vantage human login --email human@example.test
pnpm --silent vantage human accounts
pnpm --silent vantage human grants list
pnpm --silent vantage human history

Replace the example email. Login prompts for your password without displaying it; the remaining commands return your accounts, grants and activity.

To revoke one grant, use its ID from the grant list:

pnpm --silent vantage human grants revoke --grant-id GRANT_UUID

Replace GRANT_UUID. This stops access through that grant; other grants remain active.

Human commands use a separate session file. Connect bank accounts through the web app. Enter passwords at the login prompt; protected automation can use --password-stdin.

Credential settings

Setting	Purpose
`VANTAGE_AGENT_CONFIG`	Agent installation file. Default: `~/.config/vantage/agent.json`.
`VANTAGE_HUMAN_CONFIG`	Human session file. Default: `~/.config/vantage/human.json`.
`VANTAGE_AGENT_KEY`	Optional existing agent key supplied through the environment.
`VANTAGE_AGENT_KEY_FILE`	Optional protected file containing an existing agent key.

Use regular credential files with mode 0600. The saved installation file pairs the key with its API origin. With environment or raw-key-file overrides, choose the matching VANTAGE_API_URL.

Store keys in the private installation file or protected environment settings.

Local development

The CLI defaults to http://127.0.0.1:4000. To use a local stack, install Docker Engine with Compose v2 and GNU Make, configure Plaid credentials, then run:

make dev
make health
export VANTAGE_API_URL=http://127.0.0.1:4000
export VANTAGE_AGENT_CONFIG="$HOME/.config/vantage/local-agent.json"
export VANTAGE_HUMAN_CONFIG="$HOME/.config/vantage/local-human.json"

Run from the repository root. Local configuration files keep test credentials separate from hosted credentials.

Updated October 4, 2026