mercury-cli

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

Features

🏦 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

Installation

npm install -g mercury-cli

Quick Start

# 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>

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

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

Getting Your API Token

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

Token Scopes

Scope	Permissions
`read`	View accounts, transactions, recipients
`offline_access`	Refresh token access
`SendMoney`	Initiate transfers and payments
`RequestCards`	Create debit cards

`mercury login`

Store an API token for authentication.

Syntax:

mercury login --token <TOKEN>
mercury 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:

# 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:

Error	Cause	Solution
`Missing token`	Neither `--token` nor `--token-stdin` provided	Provide token via one of the methods
`Token cannot be empty`	Empty string provided	Ensure token is not empty
`Use either --token or --token-stdin, not both`	Both flags used	Use only one method

`mercury logout`

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.

`mercury status`

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:

Field	Description
`Authenticated`	Yes/No
`Token`	Masked token (first 10 + last 4 chars)
`API Base URL`	API endpoint being used
`Default Account`	If configured in config.json

Token Storage & Configuration

File Locations

File	Purpose	Permissions
`~/.mercury/token`	API token	`600` (owner read/write only)
`~/.mercury/config.json`	Optional configuration	`600`

Configuration File

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

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

Field	Type	Default	Description
`defaultAccountId`	string	none	Account ID to use when not specified
`apiBaseUrl`	string	`https://api.mercury.com/api/v1`	API endpoint

Security Best Practices

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

Accounts

Manage Mercury bank accounts.

Aliases: account, acc

`mercury accounts` / `mercury accounts list`

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"
  }
]

`mercury accounts get`

Get detailed information about a specific account.

Syntax:

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

Parameters:

Parameter	Required	Description
`account-id`	Yes	The UUID of the account

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

Transactions

View and send transactions.

Aliases: tx, txn

`mercury transactions`

List transactions for an account.

Syntax:

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

Parameters:

Parameter	Required	Description
`account-id`	Yes	The UUID of the account

Options:

Option	Type	Default	Description
`--limit <N>`	integer	25	Maximum number of transactions to return
`--offset <N>`	integer	0	Number of transactions to skip (for pagination)
`--status <status>`	string	all	Filter by status: `pending`, `sent`, `cancelled`, `failed`
`--start <date>`	ISO date	none	Filter transactions on or after this date
`--end <date>`	ISO date	none	Filter transactions on or before this date
`--search <query>`	string	none	Search by counterparty name

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

`mercury transactions get`

Get detailed information about a specific transaction.

Syntax:

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

Parameters:

Parameter	Required	Description
`account-id`	Yes	The UUID of the account
`transaction-id`	Yes	The UUID of the transaction

`mercury transactions send`

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:

Option	Required	Type	Description
`--recipient <id>`	Yes	string	Recipient UUID
`--amount <cents>`	Yes	integer	Amount in cents (e.g., `10000` = $100.00)
`--idempotency-key <key>`	Yes	string	Unique key to prevent duplicate transactions
`--method <method>`	No	string	Transfer method: `ach` (default) or `wire`
`--note <note>`	No	string	Internal note for the transaction

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

Internal Transfers

`mercury transfer`

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:

Option	Required	Type	Description
`--from <id>`	Yes	string	Source account UUID
`--to <id>`	Yes	string	Destination account UUID
`--amount <cents>`	Yes	integer	Amount in cents
`--idempotency-key <key>`	Yes	string	Unique key to prevent duplicates
`--note <note>`	No	string	Internal note

Recipients

Manage payment recipients (external bank accounts).

Aliases: recipient, recip

`mercury recipients` / `mercury recipients list`

List all recipients.

Syntax:

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

`mercury recipients get`

Get detailed information about a recipient.

Syntax:

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

`mercury recipients add`

Add a new payment recipient.

Syntax:

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

Options:

Option	Required	Type	Description
`--name <name>`	Yes	string	Recipient name
`--account <number>`	Yes	string	Bank account number
`--routing <number>`	Yes	string	Bank routing number (9 digits)
`--bank-name <name>`	No	string	Name of the bank
`--account-type <type>`	No	string	Account type
`--email <email>`	No	string	Contact email (repeatable)

Account Types: businessChecking, businessSavings, personalChecking, personalSavings

`mercury recipients delete`

Delete a recipient.

Syntax:

mercury recipients delete <recipient-id>

Cards

Aliases: card

`mercury cards`

List cards for an account.

Syntax:

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

Card Statuses: active, frozen, cancelled

Statements

Aliases: statement

`mercury statements`

List statements for an account.

Syntax:

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

`mercury statements get`

Get a specific statement.

Syntax:

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

Webhooks

Aliases: webhook, wh

`mercury webhooks` / `mercury webhooks list`

List all webhook endpoints.

Syntax:

mercury webhooks [list] [--json]

`mercury webhooks get`

Get details about a webhook.

Syntax:

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

`mercury webhooks create`

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)

`mercury webhooks update`

Update an existing webhook.

Syntax:

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

`mercury webhooks delete`

Delete a webhook endpoint.

Syntax:

mercury webhooks delete <webhook-id>

`mercury webhooks verify`

Send a test event to verify webhook connectivity.

Syntax:

mercury webhooks verify <webhook-id>

Events

Aliases: event

`mercury events` / `mercury events list`

List API events (audit trail).

Syntax:

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

`mercury events get`

Get details about a specific event.

Syntax:

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

Organization

Aliases: org

`mercury organization`

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

Syntax:

mercury organization [--json]

Users

Aliases: user

`mercury users` / `mercury users list`

List all users in the organization.

Syntax:

mercury users [list] [--json]

`mercury users get`

Get details about a specific user.

Syntax:

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

Error Handling

Common Errors

HTTP Code	Error	Cause	Solution
401	`Not authenticated`	Missing or invalid token	Run `mercury login`
403	`Forbidden`	Token lacks required scope	Get token with appropriate permissions
404	`Not found`	Resource doesn't exist	Verify the ID
422	`Validation error`	Invalid parameters	Check format and values
429	`Rate limited`	Too many requests	Wait and retry

Scripting Examples

Export Transactions to CSV

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

Daily Balance Check

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

API Reference

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

Endpoint Mapping

CLI Command	HTTP Method	API Endpoint
`accounts list`	GET	`/accounts`
`accounts get <id>`	GET	`/account/{id}`
`transactions list`	GET	`/account/{id}/transactions`
`transactions send`	POST	`/account/{id}/transactions`
`transfer`	POST	`/transfer`
`recipients list`	GET	`/recipients`
`recipients add`	POST	`/recipients`
`recipients delete <id>`	DELETE	`/recipient/{id}`
`cards`	GET	`/account/{id}/cards`
`statements list`	GET	`/account/{id}/statements`
`webhooks list`	GET	`/webhooks`
`webhooks create`	POST	`/webhooks`
`events list`	GET	`/events`
`organization`	GET	`/organization`
`users list`	GET	`/users`
`categories`	GET	`/categories`

License

MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
bin		bin
sources		sources
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
hero.png		hero.png
package.json		package.json
tsconfig.json		tsconfig.json

License

ex3ndr/mercury-cli

Folders and files

Latest commit

History

Repository files navigation

mercury-cli

Features

Installation

Quick Start

Global Options

Authentication

Getting Your API Token

Token Scopes

mercury login

mercury logout

mercury status

Token Storage & Configuration

File Locations

Configuration File

Security Best Practices

Accounts

mercury accounts / mercury accounts list

mercury accounts get

Transactions

mercury transactions

mercury transactions get

mercury transactions send

Internal Transfers

mercury transfer

Recipients

mercury recipients / mercury recipients list

mercury recipients get

mercury recipients add

mercury recipients delete

Cards

mercury cards

Statements

mercury statements

mercury statements get

Webhooks

mercury webhooks / mercury webhooks list

mercury webhooks get

mercury webhooks create

mercury webhooks update

mercury webhooks delete

mercury webhooks verify

Events

mercury events / mercury events list

mercury events get

Organization

mercury organization

Users

mercury users / mercury users list

mercury users get

Categories

mercury categories

Error Handling

Common Errors

Scripting Examples

Export Transactions to CSV

Daily Balance Check

API Reference

Endpoint Mapping

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 3

Uh oh!

Languages

`mercury login`

`mercury logout`

`mercury status`

`mercury accounts` / `mercury accounts list`

`mercury accounts get`

`mercury transactions`

`mercury transactions get`

`mercury transactions send`

`mercury transfer`

`mercury recipients` / `mercury recipients list`

`mercury recipients get`

`mercury recipients add`

`mercury recipients delete`

`mercury cards`

`mercury statements`

`mercury statements get`

`mercury webhooks` / `mercury webhooks list`

`mercury webhooks get`

`mercury webhooks create`

`mercury webhooks update`

`mercury webhooks delete`

`mercury webhooks verify`

`mercury events` / `mercury events list`

`mercury events get`

`mercury organization`

`mercury users` / `mercury users list`

`mercury users get`

`mercury categories`

Packages