Firefly III Command Line Interface

A python-based command line interface for conveniently entering expenses in Firefly III.

Instalation

This CLI tool is available on PyPI and as a docker image.

1. Install from PyPI

# Install firefly-cli from PyPI
pip install firefly-cli

# Enjoy! Runs firefly-cli
firefly-cli

2. Docker Image

Currently, there are images for x86-64, arm64 and arm/v7 architectures.

They are built from python's Linux Alpine base image (python:3.9-alpine) which makes the application very slim (less than 20MB).

Architecture	Tag
x86-64	latest
arm64	latest
arm/v7	latest

There are also development images with the latest on master branch:

Architecture	Tag
x86-64	dev-latest
arm64	dev-latest
arm/v7	dev-latest

Getting started with firefly-cli Docker:

# Pull latest image
docker pull afonsoc12/firefly-cli:latest

# Test if it is working, mount path to your firefly-cli config folder
docker run --rm -it \
           -v ~/.config/firefly-cli:/config/firefly-cli \
           afonsoc12/firefly-cli:latest

# Set an alias on your .bashrc or .zshrc, so that it is more convenient to run
alias firefly-cli="docker run --rm -it -v ~/.config/firefly-cli:/config/firefly-cli afonsoc12/firefly-cli:latest"

# Add some transactions!
firefly-cli add 5, Large Mocha, Cash, Starbucks

3. Bare Python

Alternatively, you can clone the repository and install from setup.py or run as a python module.

From setup.py:

# Clone the repository
git clone https://github.com/afonsoc12/firefly-cli.git

# Go to root directory
cd firefly-cli

# Install firefly-cli
pip install .

# Run firefly-cli
firefly-cli

Python module:

# Clone the repository
git clone https://github.com/afonsoc12/firefly-cli.git

# Go to root directory
cd firefly-cli

# Install dependencies
pip install -r requirements.txt

# Run module as a script
python -m firefly_cli

Usage

The CLI has two modes of operation:

1. In one-line command style:

$ firefly-cli add 5.2, Large Mocha, Cash, Starbucks

2. Command Line Interface:

$ firefly-cli

Copyright 2022 Afonso Costa

Licensed under the Apache License, Version 2.0 (the "License");
Type "license" for more information.

Welcome to FireflyIII Command Line Interface!
Created by Afonso Costa (@afonsoc12)

=============== Status ===============
  - URL: https://firefly.mydomain.com
  - API Token: *****iUcHo
  - Connection: OK!
  - Version: 0.1.0
======================================

Type "help" to list commands.

🐷 ➜

Setup

If you run firefly-cli straight away, a warning will pop up since you haven't configured it with your FireflyIII instance.

In order to configure your Firefly III URL and API_TOKEN you have to run these two commands (you can find here how to get your API Personal Access Token:

# Start CLI, well this one does not count as a command 🙃
firefly-cli

# Set your Firefly URL, such as https://firefly.mydomain.com
🐷 ➜ edit URL <YOUR URL>

# Set your Firefly API_TOKEN
🐷 ➜ edit API_TOKEN <YOUR API TOKEN>

After entering these values, firefly-cli will automatically refresh API connection. At any point, you can trigger a connection refresh:

# Refreshes API connection
🐷 ➜ refresh

Alternatively, you can create a firefly-cli.ini file and place it in $XDG_CONFIG_HOME/firefly-cli/firefly-cli.ini with the following content:

[API]
url = https://firefly.yourdomain.com
api_token = eyXXX

Note: If $XDG_CONFIG_HOME is not set, it defaults to $HOME/.config/firefly-cli/firefly-cli.ini

firefly-cli can override this behaviour and read/write from the file specified by the environment variable FIREFLY_CLI_CONFIG.

Commands

The scope of this CLI is to enter expenses in a comma-separated style.

Starting in v0.1.0, it now supports adding all possible transaction fields using optional arguments (e.g. --source-name "Bank HSBC"). The comma-separated arguments (aka positional arguments) are maintained for backwards-compatibility, but optional arguments will always override the comma-separated ones

Summary of the available commands:

Command	Description
help	Shows the available commands.
accounts	Shows budgets information (UI unpolished).
add	Adds a transaction to FireflyIII (See add section).
budgets	Shows budgets information (UI unpolished).
edit	Edits URL and API_TOKEN parameters. Type edit [URL/API_TOKEN] ` to configure firefly-cli with your Firefly instance.
exit	Exits the CLI tool.
help	Shows available commands. Type help [command] to display information about that command.
license	Shows License information.
refresh	Refreshes API connection.
version	Shows firefly-cli version.

Adding a transaction

The command add is responsible for entering a new transaction in your Firefly instance. Further help can be shown by typing add --help or help add.

By default, every transaction is a withdrawal and is placed with the current date and time. You may change transaction type by including the optional argument --type, change the transaction date with --date yyyy-mm-dd or if you would like to be more precise --datetime yyyy-mm-ddTHH:MM:SS.

The comma-separated fields available are the following:

Amount, Description , Source account, Destination account, Category, Budget

The first four fields can NEVER be omitted!

Examples

# These four fields are mandatory
# Mandatory fields: amount, description, source_account, destination_account
🐷 ➜ add 5, Large Mocha, Cash, Starbucks

# Don't need to be exclusively comma-separated fields, as long as they are specified
🐷 ➜ add --amount 5 --description "Large Mocha" --source-name Cash --destination-name Starbucks

# Or a mixture of comma-separated and optional arguments
🐷 ➜ add 5, Large Mocha --source-name Cash --destination-name Starbucks

# Remember: optional arguments ALWAYS override comma-separated ones
🐷 ➜ add 5, Large Mocha, Cash, Starbucks --source-name "Bank HSBC"
# will create a transaction whose source is "Bank HSBC" and NOT "Cash"

# You can skip specfic fields by leaving them empty
🐷 ➜ add 5, Large Mocha, Cash, Starbucks, , Morning Coffees
# sets the budget to "Morning Coffees" and skips the category

Credits

Copyright 2022 Afonso Costa

Licensed under the Apache License, Version 2.0 (the "License")

FireflyIII logo extracted from the official FireflyIII website