Exchangerate Api CLI

Every ExchangeRate-API endpoint, plus a local rate history, watchlists, drift alerts, and an MCP server no one else ships.

This CLI exposes every ExchangeRate-API endpoint (latest, pair, codes, quota, enriched, history) as typed commands and layers on offline-first features the API can't provide: local snapshots in SQLite, watchlists with drift alerts, quota burn projection, N×N cross-rate matrices from a single API call, and an MCP server for AI agents. Free-tier users get time travel from their own captured history without paying for /history access.

Created by @vinnyp (Vinny Pasceri).

Authentication

Set EXCHANGERATE_API_KEY from your ExchangeRate-API dashboard (https://app.exchangerate-api.com/). All commands route through https://v6.exchangerate-api.com/v6/{key}/.... The open command uses the keyless https://open.er-api.com/v6/latest/{base} endpoint and requires the 'Rates By Exchange Rate API' attribution if you redistribute its output.

Quick Start

# Confirms key works and the API is reachable
exchangerate-api-pp-cli doctor

# Pulls latest rates and seeds local snapshots; foundation for offline + history features
exchangerate-api-pp-cli sync-rates --base USD

# Single-pair lookup, the most common request
exchangerate-api-pp-cli rates pair USD EUR

# Multi-target conversion with one API call
exchangerate-api-pp-cli convert 250 USD EUR,GBP,JPY --json

# Cross-rate matrix — N² rates, 1 quota tick
exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY --base USD --json

# How fast you're burning the monthly 1500-call quota
exchangerate-api-pp-cli quota burn --json

Unique Features

These capabilities aren't available in any other tool for this API.

Local state that compounds

• history-cache — Reconstruct historical FX rates from your prior latest syncs — free tier gets time travel without /history quota.

  Use when the user asks for past rates and the API key is on the Free or Standard tier where /history returns plan-upgrade-required.

  exchangerate-api-pp-cli history-cache USD EUR --since 30d --json
  

• watch check — Define currency pairs with movement thresholds; one command reports which crossed since the last check.

  Use as a periodic monitor (cron/agent loop) instead of polling a paid alerting service.

  exchangerate-api-pp-cli watch check --json
  

• drift — Diff the latest snapshot against any prior point and report the biggest movers as ranked output.

  Use to surface unusual FX moves the user cares about without writing a custom analysis.

  exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json
  

• pair --as-of — Look up the rate from local snapshots at any historical timestamp — free tier time travel.

  Use when reconstructing the rate that was live at a specific moment without needing the paid /history endpoint.

  exchangerate-api-pp-cli rates pair USD EUR --as-of 1h --json
  

Quota intelligence

• quota burn — Fit a trend over quota_snapshots and project when your quota will exhaust before refresh day.

  Use before deploying anything that will hammer the API — the projection tells you if you'll survive the month.

  exchangerate-api-pp-cli quota burn --json
  

• matrix — Show full cross-rate matrix for any set of currencies from a single latest call — N² rates, 1 quota tick.

  Use when comparing many pairs at once; saves quota and runs offline after one sync.

  exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY --base USD --json
  

• convert-batch — Pipe a list of amounts to a single command; converts all of them with one rate fetch.

  Use when processing many amounts (orders, transactions) without burning the quota linearly.

  exchangerate-api-pp-cli convert-batch --from USD --to EUR --input /dev/null --json
  

Onboarding

• plan-check — Probe each tier-gated endpoint with a single low-cost request; reports which tier your key supports.

  Use right after doctor to know which commands will work without plan-upgrade-required.

  exchangerate-api-pp-cli plan-check --json
  

Agent-native plumbing

• log show — Every convert call is logged; query the log by base, target, time window for recurring conversion analysis.

  Use to remind an agent what FX work was done recently without re-querying the API.

  exchangerate-api-pp-cli log show --since 7d --json
  

• mcp serve — Every user-facing command is exposed as an MCP tool with read-only annotations on safe queries.

  Use when wiring Claude/Cursor/Windsurf to FX context — no competing MCP for this API today.

  exchangerate-api-pp-cli mcp serve
  

Usage

Run exchangerate-api-pp-cli --help for the full command reference and flag list.

Commands

The API key is supplied via the EXCHANGERATE_API_KEY environment variable, never as a positional argument — every command below reads it from the environment.

codes

Supported currency codes

• exchangerate-api-pp-cli codes - List all 161 supported currency codes

quota

Your API quota usage

• exchangerate-api-pp-cli quota - Check remaining requests in the current quota period
• exchangerate-api-pp-cli quota burn - Project quota exhaustion from quota_snapshots history

rates

Live exchange rates and conversions

• exchangerate-api-pp-cli rates latest <base_code> - Get all exchange rates from a base currency
• exchangerate-api-pp-cli rates pair <base_code> <target_code> - Get conversion rate between two currencies
• exchangerate-api-pp-cli rates pair-amount <base_code> <target_code> <amount> - Convert a specific amount between two currencies
• exchangerate-api-pp-cli rates enriched <base_code> <target_code> - Pair conversion with locale, flag, and currency display metadata (Business/Volume tier)
• exchangerate-api-pp-cli rates history <base_code> <year> <month> <day> - Historical exchange rates for a specific date (Pro/Business/Volume tier)

Conversion & analysis (novel)

• exchangerate-api-pp-cli convert <amount> <from> <to[,to,...]> - Convert an amount; multi-target uses a single API call
• exchangerate-api-pp-cli convert-batch --from USD --to EUR --input - - Batch convert amounts piped on stdin
• exchangerate-api-pp-cli matrix <currencies> - N×N cross-rate matrix from a single /latest call
• exchangerate-api-pp-cli pair --as-of <timestamp> - Look up the rate from local snapshots at any past time
• exchangerate-api-pp-cli history-cache <base> <target> - Reconstruct historical rates from prior latest syncs

Local data & monitoring (novel)

• exchangerate-api-pp-cli sync-rates --base USD - Pull latest rates and seed local snapshots
• exchangerate-api-pp-cli drift --base USD --since 24h - Diff latest snapshot vs prior and rank movers
• exchangerate-api-pp-cli watch check - Report watched pairs that crossed their thresholds
• exchangerate-api-pp-cli log show - Query recent convert calls from the local log
• exchangerate-api-pp-cli plan-check - Probe tier-gated endpoints to see what your key supports

Utilities

• exchangerate-api-pp-cli doctor - Verify credentials and API reachability
• exchangerate-api-pp-cli open - Keyless open.er-api.com lookup (rate-limited, attribution required)
• exchangerate-api-pp-cli mcp serve - Run as an MCP server for AI agents

Output Formats

# Human-readable table (default in terminal, JSON when piped)
exchangerate-api-pp-cli codes

# JSON for scripting and agents
exchangerate-api-pp-cli codes --json

# Filter to specific fields
exchangerate-api-pp-cli codes --json --select supported_codes

# Dry run — show the request without sending
exchangerate-api-pp-cli rates pair USD EUR --dry-run

# Agent mode — JSON + compact + no prompts in one flag
exchangerate-api-pp-cli rates pair USD EUR --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Recipes

End-to-end workflows agents and scripts commonly need. Each is ready to copy-paste.

One-shot conversion in a script

exchangerate-api-pp-cli convert 1000 USD EUR --json --select results.0.result

Returns just the converted number for downstream piping.

Daily sync + drift report (cron)

exchangerate-api-pp-cli sync-rates --base USD && \
  exchangerate-api-pp-cli drift --base USD --since 24h --top 10 --json

Captures today's rates and surfaces the largest movers vs the prior snapshot.

Pre-deploy quota check

exchangerate-api-pp-cli quota burn --json --select projected_exhaustion,requests_remaining

Projects when the monthly quota will run out, given recent usage. Run before any deploy that will hammer the API.

Cross-rate matrix for a portfolio

exchangerate-api-pp-cli matrix USD,EUR,GBP,JPY,CHF,CAD --base USD --csv

Full N×N matrix from one API call — N² rates, 1 quota tick. Pipes cleanly into spreadsheets.

Watch a pair and alert when it moves

exchangerate-api-pp-cli watch add USD EUR --threshold 1.0
exchangerate-api-pp-cli watch check --json --select alerts

Stores a threshold per pair; subsequent watch check calls flag any pair that crossed.

Time-travel a rate from local history

# After 'sync-rates --base USD' has populated rates_snapshots:
exchangerate-api-pp-cli rates pair USD EUR --as-of 30d --json

Reads the closest captured rate at-or-before the timestamp. Falls back to the live API for recent (≤24h) cutoffs when no snapshot exists.

Health Check

exchangerate-api-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/exchangerate-api-pp-cli/config.yaml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
EXCHANGERATE_API_KEY	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run exchangerate-api-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $EXCHANGERATE_API_KEY Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• error-type: invalid-key — Run exchangerate-api-pp-cli doctor to confirm EXCHANGERATE_API_KEY is exported in the current shell.
• error-type: quota-reached — Hit your monthly limit. Use cached data via pair --as-of, history-cache, or wait until your refresh day (see quota output).
• error-type: plan-upgrade-required on enriched/history — Those endpoints require a paid tier. Use plan-check to see which endpoints your key supports.
• history returns nothing — Fall back to local snapshots: history-cache <BASE> <TARGET> if you've been syncing.
• open rate-limited (HTTP 429) — Open-access endpoint resets after 20 minutes. Switch to a keyed latest <BASE> call.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• wesbos/currency-conversion-mcp — TypeScript (35 stars)
• TimothyYe/exchangerate — Go (33 stars)
• markwragg/PowerShell-CurrencyConverter — PowerShell (6 stars)
• VersBinarii/poile — Rust (3 stars)
• cahthuranag/realtime-exchange-rate-mcp — TypeScript

Generated by CLI Printing Press