mercury-cli

A powerful CLI for the Mercury Banking API. Manage accounts, transactions, recipients, webhooks, and more from your terminal.

• 🏦 Full Mercury API coverage — accounts, transactions, transfers, recipients, webhooks, and more
• 📊 Multiple output formats — human-readable tables or JSON for scripting
• 🔐 Secure token storage — credentials stored safely in ~/.mercury/
• ⚡ Fast — lightweight with minimal dependencies
• 🤖 Scriptable — no interactive prompts, perfect for CI/CD and automation

npm install -g mercury-cli

# 1. Get your API token from Mercury Dashboard
#    https://app.mercury.com/settings/api

# 2. Authenticate
mercury login --token <YOUR_API_TOKEN>

# 3. List your accounts
mercury accounts

# 4. View transactions
mercury transactions <account-id>

All commands support these global options:

Mercury CLI uses API tokens for authentication. Tokens are stored locally in ~/.mercury/token with restricted permissions (mode 600).

1. Log in to Mercury Dashboard
2. Navigate to Settings → API
3. Click Create API Token
4. Choose token permissions:
   • Read-only: Can fetch all data, cannot initiate transactions
   • Read-write: Full access including payments
   • Custom: Fine-grained scope control
5. Copy the token (format: secret-token:mercury_production_...)

Store an API token for authentication.

Syntax:

mercury login --token <TOKEN>
mercury login --token-stdin

Flags:

Examples:

# Direct token input
mercury login --token "secret-token:mercury_production_wma_xxx"

# From environment variable
mercury login --token "$MERCURY_TOKEN"

# From stdin (CI/CD friendly)
echo "$MERCURY_TOKEN" | mercury login --token-stdin

# From file
cat ~/.secrets/mercury | mercury login --token-stdin

Success Response:

Authenticated successfully. Token saved to ~/.mercury/token

Error Cases:

Remove stored authentication token.

Syntax:

mercury logout

Examples:

mercury logout
# Output: Logged out. Token removed from ~/.mercury/token

# If not logged in:
mercury logout
# Output: Not currently authenticated.

Show current authentication and configuration status.

Syntax:

mercury status

Example Output:

Mercury CLI Status
──────────────────
Authenticated: Yes
Token: secret-tok...xxxx
API Base URL: https://api.mercury.com/api/v1
Default Account: abc123-def456-...

Fields:

Optional configuration at ~/.mercury/config.json:

{
  "defaultAccountId": "abc123-def456-...",
  "apiBaseUrl": "https://api.mercury.com/api/v1"
}

1. Never commit tokens — Add .mercury/ to .gitignore
2. Use environment variables in CI — Don't hardcode tokens
3. Rotate tokens periodically — Regenerate from Mercury Dashboard
4. Use read-only tokens when possible — Minimize risk

Manage Mercury bank accounts.

Aliases: account, acc

List all accounts.

Syntax:

mercury accounts [list] [--json]

Example Output:

ID                                    Name                  Type          Status      Available        Current
──────────────────────────────────    ────────────────────  ────────────  ──────────  ───────────────  ───────────────
abc123-def456-...                     Operating Account     checking      active      $125,432.10      $125,432.10
xyz789-uvw012-...                     Savings               savings       active      $50,000.00       $50,000.00

JSON Response:

[
  {
    "id": "abc123-def456-...",
    "name": "Operating Account",
    "status": "active",
    "type": "checking",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "currentBalance": 12543210,
    "availableBalance": 12543210,
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Get detailed information about a specific account.

Syntax:

mercury accounts get <account-id> [--json]

Parameters:

Example:

mercury accounts get abc123-def456-789a-bcde-f01234567890

Output:

Account Details
───────────────
ID:              abc123-def456-789a-bcde-f01234567890
Name:            Operating Account
Type:            checking
Status:          active
Account Number:  1234567890
Routing Number:  021000021
Available:       $125,432.10
Current:         $125,432.10
Created:         Jan 15, 2024

Account Types:

• checking — Standard business checking account
• savings — Business savings account
• mercury_treasury — Mercury Treasury account

Account Statuses:

• active — Account is open and operational
• pending — Account is being set up
• closed — Account has been closed

View and send transactions.

Aliases: tx, txn

List transactions for an account.

Syntax:

mercury transactions <account-id> [options] [--json]

Parameters:

Options:

Examples:

# List recent transactions
mercury transactions abc123-def456-...

# With pagination
mercury transactions abc123-def456-... --limit 50 --offset 100

# Filter by status
mercury transactions abc123-def456-... --status pending

# Filter by date range
mercury transactions abc123-def456-... --start 2024-01-01 --end 2024-12-31

# Search by counterparty
mercury transactions abc123-def456-... --search "Acme Corp"

Transaction Statuses:

• pending — Transaction is being processed
• sent — Transaction completed successfully
• cancelled — Transaction was cancelled
• failed — Transaction failed

Transaction Kinds:

• externalTransfer — ACH or wire transfer to external account
• internalTransfer — Transfer between Mercury accounts
• outgoingPayment — Check or other outgoing payment
• incomingPayment — Received payment

Get detailed information about a specific transaction.

Syntax:

mercury transactions get <account-id> <transaction-id> [--json]

Parameters:

Send money to a recipient via ACH or wire transfer.

Syntax:

mercury transactions send <account-id> --recipient <id> --amount <cents> --idempotency-key <key> [options] [--json]

Options:

Examples:

# Send $100 via ACH
mercury transactions send abc123-def456-... \
  --recipient recip-123 \
  --amount 10000 \
  --idempotency-key "invoice-2024-001"

# Send $500 via Wire with note
mercury transactions send abc123-def456-... \
  --recipient recip-123 \
  --amount 50000 \
  --idempotency-key "wire-2024-001" \
  --method wire \
  --note "Urgent payment"

Important Notes:

• Amounts are always in cents (smallest currency unit)
• Idempotency keys prevent duplicate transactions if the request is retried
• Wire transfers typically have higher fees but faster delivery
• ACH transfers take 1-3 business days

Transfer funds between two Mercury accounts you own.

Syntax:

mercury transfer --from <account-id> --to <account-id> --amount <cents> --idempotency-key <key> [options] [--json]

Options:

Manage payment recipients (external bank accounts).

Aliases: recipient, recip

List all recipients.

Syntax:

mercury recipients [list] [--limit <N>] [--offset <N>] [--json]

Get detailed information about a recipient.

Syntax:

mercury recipients get <recipient-id> [--json]

Add a new payment recipient.

Syntax:

mercury recipients add --name <name> --account <number> --routing <number> [options] [--json]

Options:

Account Types: businessChecking, businessSavings, personalChecking, personalSavings

Delete a recipient.

Syntax:

mercury recipients delete <recipient-id>

Aliases: card

List cards for an account.

Syntax:

mercury cards <account-id> [--json]

Card Statuses: active, frozen, cancelled

Aliases: statement

List statements for an account.

Syntax:

mercury statements <account-id> [--json]

Get a specific statement.

Syntax:

mercury statements get <account-id> <statement-id> [--json]

Aliases: webhook, wh

List all webhook endpoints.

Syntax:

mercury webhooks [list] [--json]

Get details about a webhook.

Syntax:

mercury webhooks get <webhook-id> [--json]

Create a new webhook endpoint.

Syntax:

mercury webhooks create --url <url> [--events <event1,event2>] [--secret <secret>] [--json]

Event Types: transaction.created, transaction.updated, account.created, recipient.created, * (wildcard)

Update an existing webhook.

Syntax:

mercury webhooks update <webhook-id> [--url <url>] [--events <events>] [--status <status>] [--json]

Delete a webhook endpoint.

Syntax:

mercury webhooks delete <webhook-id>

Send a test event to verify webhook connectivity.

Syntax:

mercury webhooks verify <webhook-id>

Aliases: event

List API events (audit trail).

Syntax:

mercury events [list] [--limit <N>] [--offset <N>] [--type <type>] [--json]

Get details about a specific event.

Syntax:

mercury events get <event-id> [--json]

Aliases: org

Get organization information (legal name, EIN, address).

Syntax:

mercury organization [--json]

Aliases: user

List all users in the organization.

Syntax:

mercury users [list] [--json]

Get details about a specific user.

Syntax:

mercury users get <user-id> [--json]

Aliases: category, cat

List available transaction categories.

Syntax:

mercury categories [--json]

mercury transactions "$ACCOUNT_ID" --limit 1000 --json | \
  jq -r '.transactions[] | [.id, .status, .amount, .counterpartyName] | @csv'

balance=$(mercury accounts get "$ACCOUNT_ID" --json | jq -r '.availableBalance')
echo "Balance: $((balance / 100)) dollars"

• Base URL: https://api.mercury.com/api/v1
• Authentication: Bearer token
• Rate Limits: 100 requests per minute
• Documentation: docs.mercury.com/reference

MIT License. See LICENSE for details.