afonsoc12 / firefly-cli

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

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

firefly-cli's Issues

Tab autocompletion using requests-cache

Add support for expense accounts

I would be nice to be able to:

• list expense accounts
• delete a given expense account

It would provide a nice workaround to this issue.

wrong parsing arguments with space

Problem with parsing arguments with space from cli:

$> firefly-cli add  --source-name "My Bank Account" --amount 499 --description "Food" --destination-name "Shop"
Transaction header:
+-----------------------+-------------------------+
| header__apply_rules   | header__fire_webhooks   |
|-----------------------+-------------------------|
| True                  | False                   |
+-----------------------+-------------------------+

Transaction Body:
+--------------------------+----------+---------------+---------------+--------------------+------------+
| date                     |   amount | description   | source_name   | destination_name   | type       |
|--------------------------+----------+---------------+---------------+--------------------+------------|
| Thu, 2023-04-06 19:15:25 |      499 | Food          | My            | Shop               | withdrawal |
+--------------------------+----------+---------------+---------------+--------------------+------------+

As you can see, the source name is "My" instead of "My Bank Account".
But if i do it from tui mode, it works fine:

$> firefly-cli                                                                                                                              

Copyright 2023 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://***********
  - API Token: *****
  - Version: v0.1.2
  - Connection: OK!
======================================

Type "help" to list commands.

🐷 ➜ add --source-name "My Bank Account" --amount 499 --description "Food" --destination-name "Shop" 
Transaction header:
+-----------------------+-------------------------+
| header__apply_rules   | header__fire_webhooks   |
|-----------------------+-------------------------|
| True                  | False                   |
+-----------------------+-------------------------+

Transaction Body:
+--------------------------+----------+---------------+-----------------+--------------------+------------+
| date                     |   amount | description   | source_name     | destination_name   | type       |
|--------------------------+----------+---------------+-----------------+--------------------+------------|
| Thu, 2023-04-06 19:15:53 |      499 | Food          | My Bank Account | Shop               | withdrawal |
+--------------------------+----------+---------------+-----------------+--------------------+------------+

Would you like to proceed adding the transaction? (y/n): 

Refactor INI to TOML

Support setting date for transaction

It would be extremely useful if we could set an arbitrary date when creating transactions.

Cannot be installed systemwide

The config file path is not configurable. It expects to be next to the source files

This prevents me from packaging it for Arch Linux to install system wide.

Please store all information in $XDG_CONFIG_HOME/firefly-cli and $XDG_DATA_HOME/firefly-cli

Add files from .csv file

Add feature to allow importing transactions from a file, in a comma-separated format.

It will append a column on position 0 with either the date the transaction was added to firefly or the transaction number.

Category not being added

🐷 ➜ add 2.64, Coffee, Card (€), Coffee Shop, Coffee --date 2022-02-27

The argument "URL" is not recognised.

🐷 ➜ edit URL https://firefly.my.domain.com

The argument "URL" is not recognised.

Support for image upload

Allow importing images from a file path, for one-liners.

Also, allow for auto-selecting an image from a directory, associated with #3. Find matches based on the date within image EXIF data.
Coordinates could also be uploaded if available in EXIF.