@ovra/cli

Official command-line interface for Ovra — agentic payment infrastructure, EU-native.

Designed following the Command Line Interface Guidelines: human by default, machine-friendly on demand, actionable errors.

Install

npm install -g @ovra/cli

Auth

# Default — opens your browser, confirm in the dashboard
ovra login

# CI / scripts — pipe the key from stdin
echo $OVRA_API_KEY | ovra login --with-token

# Confirm the active account
ovra whoami

# Clear stored credentials
ovra logout

How ovra login works

No more copy-pasting API keys. When you run ovra login:

1. The CLI creates a short-lived pairing session on the Ovra API.
2. It opens a link in your default browser (or prints it for SSH / CI).
3. You're already signed into the Ovra dashboard, so you just click Approve.
4. The dashboard mints a scoped API key and sends it back to your CLI via polling.

The CLI displays a 4-word pairing code (e.g. maple-river-clover-wolf). The same code appears on the confirmation page — verify they match before clicking Approve. This is the anti-phishing check: no one can trick you into authorizing someone else's session, because you'd see a different code.

SSH, Docker, WSL, CI — headless environments are auto-detected. The CLI just prints the URL and waits for you to open it on another device.

Fallbacks

# CI / scripts: pipe the key from stdin — never hits disk history
echo $OVRA_API_KEY | ovra login --with-token

# Paste a key interactively (legacy, still works — useful if you have no browser)
ovra login --paste

Resolution order

Credentials are persisted to ~/.config/ovra/config.json (mode 0600, respects $XDG_CONFIG_HOME). Every command resolves the API key in this order:

1. --key flag
2. OVRA_API_KEY env var
3. Config file written by ovra login

That means OVRA_API_KEY=... still works for CI and overrides the stored key, without ever touching disk.

# Optional: pin a workflow so every call gets correlated
export OVRA_RUN_ID=run_019d7a...

Output modes

| Mode | When | How | |---|---|---| | Human | stdout is a TTY | Default — table for lists, indented key-value for single items, ANSI colors | | JSON | Script / API consumption | --json | | Plain | grep / awk / cut pipelines | --plain (also auto-selected when piped) |

# Human — colored table
ovra accounts list

# JSON for scripts
ovra accounts list --json | jq '.data[] | select(.balanceEuros > 100)'

# Plain text for Unix pipes
ovra accounts list --plain | awk '{print $1}'

Commands

| Resource | Actions | |---|---| | login / logout / whoami | Manage stored credentials | | config | list, path | | accounts | list, get <id>, create, fund <id> | | cards | list, get <id>, issue, freeze <agent>, unfreeze <agent>, close <agent>, reveal <agent> | | agents | list, get <id>, create | | payments | list, get <id>, create | | workflows | list, get <id>, create, end <id> | | vendors | list, get <id>, create, delete <id> | | authorizations | list, get <id>, create, redeem <id>, revoke <id> | | purchases | list, get <id>, create | | collect links | list, get <id>, create, void <id> | | collect invoices | list, get <id>, create, void <id> |

Run ovra <resource> --help for resource-specific usage.

Quick start

# See what you have
ovra accounts list
ovra agents list

# Create a new agent with a policy + limits
ovra agents create \
  --name procurement-bot \
  --policy po_xxx \
  --per-tx 5000 \
  --daily 10000

# Issue a virtual card for that agent
ovra cards issue \
  --agent ag_xxx \
  --purpose "AWS cloud costs monthly"

# Send a bank payment to a vendor
ovra payments create \
  --source acc_main \
  --to vdr_hetzner \
  --amount 4800 \
  --purpose "Invoice #2026-Q1-017"

# Get paid — generate a payment link
ovra collect links create \
  --account acc_main \
  --amount 2400 \
  --description "AI strategy consulting — Q2"

# Send an itemised invoice
ovra collect invoices create \
  --account acc_main \
  --customer "Acme GmbH" \
  --email [email protected] \
  --due 2026-05-01 \
  --items '[{"description":"API calls","quantity":2000000,"unitPriceEuros":0.005}]'

# Correlate calls under a workflow
ovra workflows create --name weekly-procurement
export OVRA_RUN_ID=run_xxx
ovra payments create --source acc_main --to vdr_x --amount 100
ovra payments create --source acc_main --to vdr_y --amount 50
ovra workflows get $OVRA_RUN_ID  # full timeline of the job

Global flags

| Flag | Env | Description | |---|---|---| | --key <KEY> | OVRA_API_KEY | API key (required) | | --url <URL> | OVRA_API_URL | API base URL (default: https://api.getovra.com) | | --run <RUN_ID> | OVRA_RUN_ID | Pin all calls to a workflow | | -h, --help | — | Show help for the CLI or a resource | | -v, --version | — | Print version | | --json | — | JSON output | | --plain | — | Plain tab-separated text | | -q, --quiet | — | Minimal output (just IDs / errors) | | --verbose | — | Full response body | | --no-color | NO_COLOR=1 | Disable ANSI colors | | -y, --yes | — | Skip confirmation prompts | | --dry-run | — | Show what would happen without doing it |

Errors

Errors are actionable and include a hint:

$ ovra accounts get acc_nonexistent
✗ Account not found  (E_WALLET_NOT_FOUND)

  Status 404
  Run ovra accounts list to see your accounts.

Exit codes follow POSIX convention:

| Code | Meaning | |---|---| | 0 | Success | | 1 | Runtime error (API, network, business logic) | | 2 | Usage or configuration error (missing flag, bad input) | | 130 | Interrupted with Ctrl+C |

Destructive actions

Commands that destroy state (cards close, vendors delete, authorizations revoke, collect * void) prompt for confirmation:

$ ovra vendors delete vdr_xxx
Delete vendor vdr_xxx? [y/N] █

Skip the prompt in scripts with -y/--yes. Confirmations are also auto-skipped when stdin is not a TTY (you're piping input in).

Typo suggestions

$ ovra acount list
✗ Unknown resource: acount

  Did you mean accounts?
  Try: ovra accounts list

Dry-run

Show exactly what would happen without making any API calls:

$ ovra --dry-run accounts create --name "Deal XYZ"
(dry-run) ovra accounts create --name "Deal XYZ"

Environment variables

| Var | Purpose | |---|---| | OVRA_API_KEY | API key | | OVRA_API_URL | API base URL | | OVRA_RUN_ID | Pin calls to a workflow | | NO_COLOR | Disable colors | | FORCE_COLOR | Force colors even when piped |

License

MIT