Pull CSV with BeanHub's Direct Connect

There are many drawbacks to manually downloading CSV files from different banks. When the number of banks and accounts is small, it may still be doable. However, when you have enough accounts from numerous banks, it may not be practical to do it one by one manually regularly anymore. The good news is you can solve the problem and save valuable time by using the paid service provided by BeanHub. The bad news is that the service relies on proprietary software and is not free.

Unfortunately, it's almost impossible to make this kind of software free because it requires a tremendous amount of effort to keep track of the format of transaction data from different banks and provide them in a uniform format to the user. Security requirements and regulations make it even harder for an open-source software solution to exist. Therefore, using a paid service is unavoidable if you find a fully automated experience desirable.

Introducing BeanHub Direct Connect

Direct Connect is a feature BeanHub provides that lets you directly pull standardized bank transaction CSV files from different banks via Plaid to your computer. Plaid is a fintech startup that provides API (Application Programming Interface) to extract financial data from different banks. Even though none of these services are free nor open-sourced, on the bright side, the CSV file Direct Connect provides is in a simple, standardized format. That means software relying on this format doesn't need to care where the file comes from as long as it complies with the same format.

Diagram shows how Plaid collect transactions from banks and sync with BeanHub then eventually dump CSV files and then downloaded by your PC

You can read the article Direct Connect: Pulling transactions as CSV files from banks via Plaid directly to learn more about the feature.

Setup Direct Connect repository and connect to banks

First, you need to sign up for an account and become a paid member. BeanHub provides a 30-day risk-free trial period for the paid membership. So, if you don't find it helpful, you can cancel at any time easily, no questions asked. Once you have created an account and signed in, the next step is to create a Connect Repository. Now, you open the list of the repository page and click the Create Connect Repository button.

Once you've created the Connect Repository, you visit the repository page by clicking the link on the repositories page. Then you click the Connected Banks link on the left menu:

On the Connected Banks page, you click the Connect Bank button.

It should prompt you to a Plaid dialogue asking which bank you would like to connect to and walk you through the authentication and authorization process.

Once this is done, you have a connected bank now. We run sync periodically for you with a default schedule. You can change the schedule or settings of this bank connection by clicking the Edit button.

Install BeanHub-CLI

Next, to pull the transaction data into your local environment, you need to install BeanHub-CLI first. It's an open-source command line tool we build, providing many useful features for BeanHub users and all Beancount users. You need Python greater or equal to 3.11 installed. Then, you can run:

pip install "beanhub-cli[connect]>=2.1.0"

Please note that connect commands require some extra optional Python dependencies. Therefore, when installing the BeanHub-CLI Python package, please include connect as the extra dependency.

Next, you need to log into your BeanHub account in your local environment. It's very easy to log in to your BeanHub account with BeanHub-CLI. Simply run:

bh login

It will open up an Access Token creation page on the BeanHub website in your browser like this:

It may ask you to log into your BeanHub account on the browser first if you haven't logged in yet. If your local environment doesn't allow BeanHub-CLI to open the page in the browser automatically, you can copy the shown URL and open the page manually. Once the page is present, please compare the authentication code shown by the command line tool and the one shown on the website to ensure they are identical before granting access. You can change the scope of access grant for your login session when creating it or change it later on the BeanHub Access Token management page. For more information about the login command, please read our document here.

Sync

Next, to ensure that all the transaction data in BeanHub's database is up-to-date, you can run a sync command to make BeanHub update transactions from the banks for you immediately instead of waiting until the scheduled time arrives. To run the sync command, simply type:

bh connect sync

Dump

The final step. The dump command collects all the transactions we synced from Plaid previously with either the sync command or scheduled sync operations and dumps them into your local file system as CSV files. To run the command, simply type:

bh connect dump

Since many users may want to run a sync before the dump, we also provide a --sync argument to make it run sync first, then dump to ensure that your transaction data is up-to-date. Like this:

bh connect dump --sync

That's it. Now you have the CSV file ready locally in your current folder. We will show you how to use BeanHub Import to import CSV files into your Beancount accounting books in the next section.