expenses

expenses

A CLI tool that takes a folder with receipts and invoices and outputs a catalog in CSV, also taking care of currency conversion where needed.

It uses Free Currency API for currency conversion and caches all the exchange rates locally in your file system. You'll need an API key from Free Currency API. If your base currency is USD, you can use the free tier. If you need to convert from other currencies, you might need a paid plan depending on your usage.

If you have a paid plan on the related Currency API, you can switch to it with the --paid flag (see Using the paid Currency API below).

API Key Authorization

• Get your API key from Free Currency API
• Export it in your environment as FREECURRENCY_API_KEY with the following command:

export FREECURRENCY_API_KEY=<your_api_key>

If you are using the paid Currency API with the --paid flag, export your key as CURRENCY_API_KEY instead:

export CURRENCY_API_KEY=<your_api_key>

Rationale

Sometimes (like yearly returns time ) you just find yourself with a big lump of expense files in PDF and you need to compile a report.

Even worse if your receipts are in multiple currencies, and you need to normalize all of them to a target currency… yeah, expenses fun, tell me about that!

This tool can help you automate some of this work.

The idea is to give all your expense files a consistent name so that you can extract all the information about every expense just by its file name.

This tool enforces the following convention:

{year}-{month}-{day}-{provider}-{description}-{amount}-{currency}.pdf

For example, these are valid file names:

2021-12-15-expressvpn-subscription-12.95-USD.pdf
2021-12-18-github-support-2.00-USD.pdf
2021-12-19-mailchimp-subscription-38.12-USD.pdf
2021-12-24-slides-subscription-7.00-USD.pdf
2021-12-24-streamyard-subscription-25.00-USD.pdf
2021-12-28-aws-hosting-14.76-USD.pdf

This tool can be executed in the folder with all these files:

expenses --target-currency eur

… and it will produce a CSV output that looks like the following:

Date,Provider,Description,Amount,Currency,Rate,Total
2021-12-15,expressvpn,subscription,12.95,usd,0.888295,11.50
2021-12-18,github,support,2,usd,0.88983,1.78
2021-12-19,mailchimp,subscription,38.12,usd,0.88983,33.92
2021-12-24,slides,subscription,7,usd,0.882885,6.18
2021-12-24,streamyard,subscription,25,usd,0.882885,22.07
2021-12-28,aws,hosting,14.76,usd,0.882665,13.03

Note how the tool fetched the exchange rate (based on the invoice date and target currency) and calculated the total amount for you.

This tool adopts an opinionated workflow that might not be suitable for your reporting needs. Make sure to consult your tax advisor or accountant if you are in doubt. Of course, the author of this tool is not going to take any responsibility for your taxes or other financial liabilities! After all, you are getting this for free…

Install

From npm with:

npm i -g expenses

Usage

1. Export your Free Currency API key in your environment as FREECURRENCY_API_KEY
2. Put all your expense files in one folder
3. Rename all your expense files to follow the expected convention ({year}-{month}-{day}-{provider}-{description}-{amount}-{currency}.pdf)
4. Run expenses in the folder
5. Get the CSV output and do whatever you want with it

The CLI will also output ignored files to stderr, so the easiest way to get a clean CSV file is to run:

export FREECURRENCY_API_KEY=<your_api_key>
expenses > report.CSV

If you want to find out more about the options supported by this CLI, you can run:

expenses --help

Currency conversion

The currency conversion part leverages the Free Currency API.

Note that the current implementation caches all the retrieved exchange rates locally in your file system, so you won’t have to fetch the same exchange rate twice.

All the data is stored as JSON files in your operating system’s cache path. For instance, on macOS this will be: /Users/<your_user>/Library/Caches/expenses-cli-nodejs/

Using the paid Currency API

By default the tool talks to the free Free Currency API at https://api.freecurrencyapi.com. If you have a paid plan on the related Currency API, you can switch to its endpoint at https://api.currencyapi.com by passing the --paid flag:

export CURRENCY_API_KEY=<your_api_key>
expenses --paid > report.csv

When --paid is set, the tool:

• sends requests to https://api.currencyapi.com/v3/historical
• reads the API key from the CURRENCY_API_KEY environment variable (instead of FREECURRENCY_API_KEY)

Cached rates are kept separate per backend, so switching between the free and paid endpoints never mixes up cached data.

Contributing

In the spirit of Open Source, everyone is very welcome to contribute to this project. You can contribute just by submitting bugs or suggesting improvements opening an issue on GitHub or submitting a PR.

License

Licensed under MIT License.

Luciano Mammino.