brex-cli 0.1.0 → 2026.2.1

package/README.md

@@ -1,124 +1,554 @@
 # brex-cli
 
-CLI for the Brex APIs at `https://platform.brexapis.com`.
+![Brex CLI Hero](hero.jpg)
 
-This project was cloned from `mercury-cli` and then reworked to use Brex endpoints from:
-- Authentication: https://developer.brex.com/openapi/authentication
-- Transactions: https://developer.brex.com/openapi/transactions
-- Team: https://developer.brex.com/openapi/team
-- Payments: https://developer.brex.com/openapi/payments
-- Webhooks: https://developer.brex.com/openapi/webhooks
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+A powerful CLI for the [Brex Platform API](https://developer.brex.com/). Manage accounts, transactions, transfers, recipients, webhooks, and more from your terminal.
+
+## Features
+
+- 🏦 **Full Brex API coverage** — accounts, transactions, transfers, recipients, cards, statements, webhooks, and more
+- 📊 **Multiple output formats** — human-readable tables or JSON for scripting
+- 🔐 **Secure token storage** — credentials stored safely in `~/.brex/`
+- 💳 **Cash & card accounts** — unified interface for both account types
+- 🤖 **Scriptable** — no interactive prompts, perfect for CI/CD and automation
+
+## Installation
 
 ```bash
-bun install
-bun run build
+npm install -g brex-cli
 ```
 
-Run locally:
+### Requirements
+
+- Node.js v18 or later
+
+---
+
+## Quick Start
 
 ```bash
-bun ./sources/main.ts --help
+# 1. Get your API token from Brex Developer Portal
+#    https://developer.brex.com/
+
+# 2. Authenticate
+brex login --token <YOUR_API_TOKEN>
+
+# 3. List your accounts
+brex accounts list
+
+# 4. View transactions
+brex transactions <account-id>
 ```
 
+---
+
+## Global Options
+
+All commands support these global options:
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON instead of human-readable tables |
+| `-h`, `--help` | Show help for the command |
+| `-v`, `--version` | Show CLI version |
+
+---
+
 ## Authentication
 
-Store an API access token locally:
+Brex CLI uses API tokens for authentication. Tokens are stored locally in `~/.brex/token`.
+
+### Getting Your API Token
+
+1. Log in to the [Brex Developer Portal](https://developer.brex.com/)
+2. Create an API token with the appropriate scopes
+3. Copy the token
+
+### `brex login`
+
+Store an API token for authentication.
+
+**Syntax:**
+```
+brex login --token <TOKEN>
+brex login --token-stdin
+```
+
+**Flags:**
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--token <TOKEN>` | One of these | API token string |
+| `--token-stdin` | One of these | Read token from stdin |
+
+**Examples:**
 
 ```bash
-brex login --token <ACCESS_TOKEN>
-# or
-cat token.txt | brex login --token-stdin
+# Direct token input
+brex login --token "brex_prod_xxx..."
+
+# From environment variable
+brex login --token "$BREX_TOKEN"
+
+# From stdin (CI/CD friendly)
+echo "$BREX_TOKEN" | brex login --token-stdin
+
+# From file
+cat ~/.secrets/brex | brex login --token-stdin
 ```
 
-Token/config location:
-- `~/.brex/token`
-- `~/.brex/config.json`
+---
 
-Check status:
+### `brex logout`
+
+Remove stored authentication token.
+
+```bash
+brex logout
+```
+
+---
+
+### `brex status`
+
+Show current authentication and configuration status.
 
 ```bash
 brex status
 ```
 
-## Commands
+**Example Output:**
+```
+Brex CLI Status
+──────────────────
+Authenticated: Yes
+Token: brex_prod...xxxx
+API Base URL: https://platform.brexapis.com
+Default Account: abc123-def456-...
+```
+
+---
+
+## Token Storage & Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.brex/token` | API token |
+| `~/.brex/config.json` | Optional configuration (default account, API base URL) |
+
+---
+
+## Accounts
+
+Manage Brex bank accounts (cash and card).
+
+**Aliases:** `account`, `acc`
+
+### `brex accounts list`
+
+List all accounts.
+
+**Syntax:**
+```
+brex accounts list [--type cash|card|all] [--cursor <cursor>] [--json]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--type` | string | `all` | Account type: `cash`, `card`, or `all` |
+| `--cursor` | string | none | Pagination cursor for next page |
 
-### Accounts
+### `brex accounts get`
+
+Get detailed information about a specific account.
+
+**Syntax:**
+```
+brex accounts get <account-id> [--type cash|card] [--json]
+```
+
+---
+
+## Transactions
+
+View account transactions.
+
+**Aliases:** `tx`, `txn`
+
+### `brex transactions`
+
+List transactions for an account.
+
+**Syntax:**
+```
+brex transactions <account-id> [options] [--json]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--type` | string | `cash` | Account type: `cash` or `card` |
+| `--limit <N>` | integer | 25 | Maximum number of transactions to return |
+| `--cursor` | string | none | Pagination cursor |
+| `--start <date>` | ISO date | none | Filter transactions on or after this date |
+| `--end <date>` | ISO date | none | Filter transactions on or before this date |
+
+**Examples:**
+
+```bash
+# List recent transactions for a cash account
+brex transactions abc123-def456-...
+
+# Card transactions with limit
+brex transactions abc123-def456-... --type card --limit 50
+
+# Filter by date range
+brex transactions abc123-def456-... --start 2024-01-01 --end 2024-12-31
+
+# Paginate results
+brex transactions abc123-def456-... --cursor <cursor>
+```
+
+### `brex transactions get`
+
+Get detailed information about a specific transaction.
+
+**Syntax:**
+```
+brex transactions get <account-id> <transaction-id> [--type cash|card] [--json]
+```
+
+---
+
+## Transfers (Payments API)
+
+Create and manage outbound transfers.
+
+### `brex transfer`
+
+Send funds to a counterparty.
+
+**Syntax:**
+```
+brex transfer --from <cash-account-id> --to <counterparty-id> --amount <decimal> --idempotency-key <key> [--currency <code>] [--json]
+```
+
+**Options:**
+
+| Option | Required | Type | Description |
+|--------|----------|------|-------------|
+| `--from` | Yes | string | Source cash account ID |
+| `--to` | Yes | string | Counterparty ID (recipient) |
+| `--amount` | Yes | decimal | Amount (e.g., `125.50`) |
+| `--idempotency-key` | Yes | string | Unique key to prevent duplicate transfers |
+| `--currency` | No | string | Currency code (default: `USD`) |
+
+**Examples:**
 
 ```bash
-brex accounts list --type all
-brex accounts list --type cash --cursor <cursor>
-brex accounts get <account-id> --type cash
+# Send $125.50 to a recipient
+brex transfer --from acc-123 --to cpty-456 --amount 125.50 --idempotency-key "inv-2024-001"
 ```
 
-### Transactions
+### `brex transfer get`
+
+Get details about a specific transfer.
 
 ```bash
-brex transactions <account-id> --type cash --limit 50
-brex transactions <account-id> --type card --cursor <cursor>
-brex transactions get <account-id> <transaction-id> --type cash
+brex transfer get <transfer-id> [--json]
+```
+
+### `brex transfer list`
+
+List transfers with optional filters.
+
+**Syntax:**
+```
+brex transfer list [--status <status>] [--limit <N>] [--cursor <cursor>] [--json]
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--status` | string | Filter by status (e.g., `PROCESSING`, `COMPLETED`) |
+| `--limit` | integer | Maximum results |
+| `--cursor` | string | Pagination cursor |
+| `--from-account-id` | string | Filter by source account |
+| `--to-counterparty-id` | string | Filter by recipient |
+
+---
+
+## Recipients (Payment Counterparties)
+
+Manage payment recipients for outbound transfers.
+
+**Aliases:** `recipient`, `recip`
+
+### `brex recipients list`
+
+List all recipients.
+
+**Syntax:**
+```
+brex recipients [list] [--limit <N>] [--cursor <cursor>] [--name <name>] [--json]
 ```
 
-### Transfers (Payments API)
+### `brex recipients get`
+
+Get details about a recipient.
 
 ```bash
-brex transfer --from <cash-account-id> --to <counterparty-id> --amount 125.50 --idempotency-key <key>
-brex transfer get <transfer-id>
-brex transfer list --status PROCESSING --limit 20
+brex recipients get <counterparty-id> [--json]
 ```
 
-### Recipients (Payment Counterparties)
+### `brex recipients add`
+
+Add a new payment recipient.
+
+**Syntax:**
+```
+brex recipients add --name <name> --account <number> --routing <number> [options] [--json]
+```
+
+**Options:**
+
+| Option | Required | Type | Description |
+|--------|----------|------|-------------|
+| `--name` | Yes | string | Recipient name |
+| `--account` | Yes | string | Bank account number |
+| `--routing` | Yes | string | Bank routing number (9 digits) |
+| `--account-type` | No | string | `CHECKING` or `SAVINGS` |
+| `--country` | No | string | Country code |
+| `--currency` | No | string | Currency code |
+
+### `brex recipients delete`
+
+Delete a recipient.
 
 ```bash
-brex recipients list --limit 50
-brex recipients add --name "Vendor A" --account 123456789 --routing 021000021 --account-type CHECKING
-brex recipients get <counterparty-id>
 brex recipients delete <counterparty-id>
 ```
 
-### Cards / Users / Organization
+---
+
+## Cards
+
+View card information.
+
+**Aliases:** `card`
+
+### `brex cards list`
+
+List cards with optional filters.
+
+**Syntax:**
+```
+brex cards [list] [--user-id <user-id>] [--cursor <cursor>] [--limit <N>] [--json]
+```
+
+### `brex cards get`
+
+Get details about a specific card.
 
 ```bash
-brex cards list --user-id <user-id>
-brex cards get <card-id>
+brex cards get <card-id> [--json]
+```
+
+---
 
-brex users list --cursor <cursor>
-brex users get <user-id>
+## Users
 
-brex organization
+List and view organization members.
+
+**Aliases:** `user`
+
+### `brex users list`
+
+List all users in the organization.
+
+**Syntax:**
+```
+brex users [list] [--cursor <cursor>] [--email <email>] [--json]
 ```
 
-### Statements
+### `brex users get`
+
+Get details about a specific user.
 
 ```bash
-# Primary card account
-brex statements --scope primary
-brex statements get <statement-id> --scope primary
+brex users get <user-id> [--json]
+```
+
+---
+
+## Organization
+
+**Aliases:** `org`
+
+### `brex organization`
+
+Get organization information (legal name, DBA, status, address).
+
+```bash
+brex organization [--json]
+```
+
+---
+
+## Statements
+
+View card account statements.
+
+**Aliases:** `statement`
 
-# Additional card account
-brex statements --scope additional --account-id <card-account-id>
-brex statements get <statement-id> --scope additional --account-id <card-account-id>
+### `brex statements`
+
+List statements for a card account.
+
+**Syntax:**
 ```
+brex statements [--scope primary|additional] [--account-id <id>] [--cursor <cursor>] [--json]
+```
+
+**Options:**
 
-### Webhooks & Events
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--scope` | string | `primary` | `primary` or `additional` card account |
+| `--account-id` | string | none | Required when scope is `additional` |
+| `--cursor` | string | none | Pagination cursor |
+
+### `brex statements get`
+
+Get a specific statement.
+
+```bash
+brex statements get <statement-id> [--scope primary|additional] [--account-id <id>] [--json]
+```
+
+---
+
+## Webhooks
+
+Manage webhook endpoints.
+
+**Aliases:** `webhook`, `wh`
+
+### `brex webhooks list`
+
+List all webhook endpoints.
+
+```bash
+brex webhooks [list] [--cursor <cursor>] [--limit <N>] [--json]
+```
+
+### `brex webhooks get`
+
+Get details about a webhook.
+
+```bash
+brex webhooks get <webhook-id> [--json]
+```
+
+### `brex webhooks create`
+
+Create a new webhook endpoint.
+
+**Syntax:**
+```
+brex webhooks create --url <url> [--events <event1,event2>] [--status <status>] [--json]
+```
+
+**Event Types:** `PAYMENT_COMPLETED`, `TRANSFER_COMPLETED`, and others.
+
+### `brex webhooks update`
+
+Update an existing webhook.
+
+```bash
+brex webhooks update <webhook-id> [--url <url>] [--status <status>] [--events <events>] [--json]
+```
+
+### `brex webhooks delete`
+
+Delete a webhook endpoint.
 
 ```bash
-brex webhooks list
-brex webhooks create --url https://example.com/webhooks/brex --events PAYMENT_COMPLETED,TRANSFER_COMPLETED
-brex webhooks get <webhook-id>
-brex webhooks update <webhook-id> --status ACTIVE
 brex webhooks delete <webhook-id>
+```
+
+---
+
+## Events
 
-brex events list --event-type PAYMENT_COMPLETED --limit 25
-brex events get <event-id>
+View webhook event history.
+
+**Aliases:** `event`
+
+### `brex events list`
+
+List webhook events.
+
+**Syntax:**
+```
+brex events [list] [--event-type <type>] [--after-date <ISO>] [--before-date <ISO>] [--cursor <cursor>] [--limit <N>] [--json]
+```
+
+### `brex events get`
+
+Get details about a specific event.
+
+```bash
+brex events get <event-id> [--json]
+```
+
+---
+
+## Scripting Examples
+
+### Export Transactions to CSV
+
+```bash
+brex transactions "$ACCOUNT_ID" --json | \
+  jq -r '.[] | [.id, .status, .amount, .counterpartyName] | @csv'
+```
+
+### Daily Balance Check
+
+```bash
+brex accounts get "$ACCOUNT_ID" --type cash --json | jq -r '.availableBalance'
 ```
 
-## Notes
+---
 
-- `brex transactions send` is intentionally not used for outbound payments. Use `brex transfer`.
-- `brex categories` is currently a placeholder because there is no direct categories endpoint wired in this CLI.
+## API Reference
+
+- **Base URL:** `https://platform.brexapis.com`
+- **Authentication:** Bearer token
+- **Documentation:** [developer.brex.com](https://developer.brex.com/)
+
+### API Sources
+
+| Domain | Reference |
+|--------|-----------|
+| Authentication | [developer.brex.com/openapi/authentication](https://developer.brex.com/openapi/authentication) |
+| Transactions | [developer.brex.com/openapi/transactions](https://developer.brex.com/openapi/transactions) |
+| Team | [developer.brex.com/openapi/team](https://developer.brex.com/openapi/team) |
+| Payments | [developer.brex.com/openapi/payments](https://developer.brex.com/openapi/payments) |
+| Webhooks | [developer.brex.com/openapi/webhooks](https://developer.brex.com/openapi/webhooks) |
+
+---
 
 ## Disclaimer
 
 This is an unofficial CLI. Verify scopes, permissions, and request payload requirements in Brex docs before production use.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/dist/main.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node#!/usr/bin/env bun
 // @bun
 
 // sources/config.ts
@@ -407,7 +407,12 @@ function createBrexClient() {
       if (!response.ok) {
         let body;
         try {
-          body = await response.json();
+          const parsed = await response.json();
+          if (parsed && typeof parsed === "object") {
+            body = parsed;
+          } else {
+            body = { error: `HTTP ${response.status}`, message: response.statusText };
+          }
         } catch {
           body = { error: `HTTP ${response.status}`, message: response.statusText };
         }
@@ -956,7 +961,7 @@ function parseGetOptions2(args) {
   return { type };
 }
 async function listTransactions(context, accountId, options, format2) {
-  const pathBase = options.type === "cash" ? `/v2/accounts/cash/${accountId}/transactions` : `/v2/accounts/card/${accountId}/transactions`;
+  const pathBase = options.type === "cash" ? `/v2/transactions/cash/${accountId}` : `/v2/transactions/card/${accountId}`;
   const path = withQuery(pathBase, options);
   const response = await context.client.fetch(path);
   const transactions = response.items ?? response.transactions ?? [];
@@ -982,7 +987,7 @@ Next cursor: ${response.next_cursor}`);
   }
 }
 async function getTransaction(context, accountId, transactionId, options, format2) {
-  const path = options.type === "cash" ? `/v2/accounts/cash/${accountId}/transactions/${transactionId}` : `/v2/accounts/card/${accountId}/transactions/${transactionId}`;
+  const path = options.type === "cash" ? `/v2/transactions/cash/${accountId}/${transactionId}` : `/v2/transactions/card/${accountId}/${transactionId}`;
   const response = await context.client.fetch(path);
   const transaction = response.cash_transaction ?? response.card_transaction ?? response.transaction ?? response.item;
   if (!transaction) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "brex-cli",
-  "version": "0.1.0",
+  "version": "2026.2.1",
   "description": "CLI for Brex Banking API",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ex3ndr/brex-cli.git"
+    "url": "https://github.com/ex3ndr/brex-cli"
   },
   "license": "MIT",
   "type": "module",
@@ -29,4 +29,4 @@
     "bun-types": "^1.3.8",
     "typescript": "^5.7.3"
   }
-}
+}