GitHub - afonsoc12/firefly-cli: A python-based command line interface for conveniently entering expenses in Firefly III.

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:

In one-line command style:

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

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

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

FireflyIII logo extracted from the official FireflyIII website