How to import using the CLI

Introduction

The Data Importer can import from the command line. Either by calling the Docker container, or by using your self-managed instance.

If you use the data importer just to import data (and the web interface is unused), please read the considerations below.

Configuration

The following environment variable need to be set. This value must match the local directory. If you're using Docker, set it to /import.

IMPORT_DIR_ALLOWLIST=/your/directory

Importing CSV, camt.053 files and JSON files

Importing CSV or camt.053 data requires two separate files: the actual content (CSV or XML) and a JSON configuration file. You have get this configuration file first, by doing a single import through the UI. Once you have the JSON configuration file you can use it to import any file from your bank, assuming the structure of the file is the same.

Importing from GoCardless

If you import from GoCardless, you just need the JSON configuration file from the data importer. This can be a little confusing because GoCardless also offers JSON downloads of your raw transactions. All you need to import is the JSON file from the data importer itself. This will contain enough information to download everything from GoCardless.

Commands

Import a single (CSV or camt.053) file

Use the following command to import a single file.

Remember that the JSON file is a reference to the data importer configuration file.

# self managed (file)
php artisan importer:import file.json file.xml

# self hosted (other sources)
php artisan importer:import file.json

# docker (file)
docker exec -it [container-id] php artisan importer:import file.json file.csv

# docker (other sources)
docker exec -it [container-id] php artisan importer:import file.json

The JSON file should always point to your JSON configuration file. If you are importing CSV or camt.053 files, replace file.csv with the full path to your file.

Import a directory

Another import option is present to import everything in a directory. Here are the necessary commands.

# self managed
php artisan importer:auto-import /path/to/your/files

# docker
docker exec -it [container-id] php artisan importer:auto-import /import

• For each CSV or camt.053 file to import you need two files: my-file.xml (or my-file.csv) and my-file.json.
• CSV / camt.053 files without a JSON file will be ignored.
• JSON files without a CSV / camt.053 file will be tried as a GoCardless or Spectre import. Remember that the JSON file is a reference to the data importer configuration file, you do not need to download transactions yourself.

Automatic imports using Docker

The following command will run the data importer once. It will try to import whatever it finds in the current directory, and then exit. This is fully automated. It works by mounting the current directory to /import and importing all files.

docker run \
--rm \
-v $PWD:/import \
-e FIREFLY_III_ACCESS_TOKEN= \
-e IMPORT_DIR_ALLOWLIST=/import \
-e FIREFLY_III_URL= \
-e WEB_SERVER=false \
fireflyiii/data-importer:latest-cli

Exit codes and troubleshooting

By default, the importer also dumps the debug logs in the console. This can be useful to troubleshoot issues. The importer will also return an exit code. This can be used to determine if the import was successful or not automatically. For example, when you monitor the import remotely.