USD-BRL CLI

USD-BRL CLI is a tool that allows developers to fetch the exchange rate of USD/BRL on the last business day of the first fortnight (1st–15th) of the previous month.

To file taxes in Brazil for foreign earnings, one needs to convert that income to USD using the closed exchange rate of the payment date and then convert to BRL using the exchange rate on the last business day of the first fortnight (1st–15th) of the previous month.

The data comes from the oficial website for the Brazilian Central Bank

Prerequisites

Before you begin, ensure you have met the following requirements:

• You have Node.js >=20.19 installed on your machine.
• You have an internet connection.

Installing usdbrl-cli

To install usdbrl-cli, follow these steps:

using npm:

npm install -g usdbrl-cli

Using usdbrl-cli

To use usdbrl-cli, follow these steps:

Get the exchange rate on the last business day of the first fortnight of the past month

> usdbrl
Exchange rate on 15/07/2026: R$ 5,0721 (buy) / R$ 5,0727 (sell)

Get the exchange rate on a specific date

> usdbrl -d 10/06/2020
Exchange rate on 10/06/2020: R$ 4,8888 (buy) / R$ 4,8894 (sell)

Get the exchange rate for a list of specific dates

> usdbrl -l 10/06/2020,15/07/2020,20/08/2020
Exchange rate on 10/06/2020: R$ 4,8888 (buy) / R$ 4,8894 (sell)
Exchange rate on 15/07/2020: R$ 5,3485 (buy) / R$ 5,3491 (sell)
Exchange rate on 20/08/2020: R$ 5,6504 (buy) / R$ 5,6510 (sell)

Get the exchange rate for a period

> usdbrl -r -p 05/07/2020 10/07/2020
[
  {
    "date": "06/07/2020",
    "buyRate": "5,3079",
    "sellRate": "5,3085"
  },
  {
    "date": "07/07/2020",
    "buyRate": "5,3312",
    "sellRate": "5,3318"
  },
  {
    "date": "08/07/2020",
    "buyRate": "5,3476",
    "sellRate": "5,3482"
  },
  {
    "date": "09/07/2020",
    "buyRate": "5,2972",
    "sellRate": "5,2978"
  },
  {
    "date": "10/07/2020",
    "buyRate": "5,3434",
    "sellRate": "5,3440"
  }
]

Exit codes

Code	Meaning
0	Success
1	Runtime failure (network error, timeout, non-200 status, unparseable body, no rates published for the range)
2	Usage error (malformed date, non-existent calendar date, wrong number of --period arguments, unknown flag)

stdout carries rate data only; every diagnostic message goes to stderr, so usdbrl -r | jq and usdbrl || handle_error both work as expected.

Configuration

USDBRL_ENDPOINT overrides the BCB endpoint URL the CLI queries. This is mainly useful for testing against a local stub server; it is not needed for normal use.

Contributing to usdbrl-cli

To contribute to usdbrl-cli, follow these steps:

1. Fork this repository.
2. Create a branch: git checkout -b <branch_name>.
3. Make your changes and commit them: git commit -m '<commit_message>'
4. Push to the original branch: git push origin usdbrl-cli/<location>
5. Create the pull request.

Alternatively see the GitHub documentation on creating a pull request.

Contact

If you want to contact me you can reach me at david@berribits.com.

License

This project uses the following license: MIT.