{"id":13683153,"url":"https://github.com/afonsoc12/firefly-cli","last_synced_at":"2026-01-02T11:57:26.103Z","repository":{"id":37025477,"uuid":"314654843","full_name":"afonsoc12/firefly-cli","owner":"afonsoc12","description":"A python-based command line interface for conveniently entering expenses in Firefly III.","archived":false,"fork":false,"pushed_at":"2024-01-15T18:38:28.000Z","size":157,"stargazers_count":30,"open_issues_count":5,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-08T06:11:59.677Z","etag":null,"topics":["cli","cmd2","firefly-iii","personal-finance","pypi","python","self-hosted"],"latest_commit_sha":null,"homepage":"https://github.com/afonsoc12/firefly-cli","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afonsoc12.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["afonsoc12"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2020-11-20T19:50:57.000Z","updated_at":"2024-10-26T19:43:09.000Z","dependencies_parsed_at":"2024-01-14T16:08:55.625Z","dependency_job_id":"4aa24d0c-c232-4e21-93a6-32db613c3123","html_url":"https://github.com/afonsoc12/firefly-cli","commit_stats":{"total_commits":89,"total_committers":2,"mean_commits":44.5,"dds":"0.022471910112359605","last_synced_commit":"7abe45c7a86de1eb9511eaba0d2cba276371f706"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsoc12%2Ffirefly-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsoc12%2Ffirefly-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsoc12%2Ffirefly-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afonsoc12%2Ffirefly-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afonsoc12","download_url":"https://codeload.github.com/afonsoc12/firefly-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224212042,"owners_count":17274351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cmd2","firefly-iii","personal-finance","pypi","python","self-hosted"],"created_at":"2024-08-02T13:02:02.109Z","updated_at":"2026-01-02T11:57:26.063Z","avatar_url":"https://github.com/afonsoc12.png","language":"Python","funding_links":["https://github.com/sponsors/afonsoc12"],"categories":["Python"],"sub_categories":[],"readme":"\u003cimg src=\"https://www.firefly-iii.org/assets/logo/color.png\" width=\"150\"\u003e\n\n# Firefly III Command Line Interface\n[![Docker Pulls](https://img.shields.io/docker/pulls/afonsoc12/firefly-cli?logo=docker)](https://hub.docker.com/repository/docker/afonsoc12/firefly-cli)\n[![PyPi Version](https://img.shields.io/pypi/v/firefly-cli.svg)](https://pypi.org/project/firefly-cli/)\n\n[![Github Release](https://img.shields.io/github/v/release/afonsoc12/firefly-cli?logo=github)](https://github.com/afonsoc12/firefly-cli/releases)\n[![Github Stars](https://img.shields.io/github/stars/afonsoc12/firefly-cli?logo=github)](https://github.com/afonsoc12/firefly-cli)\n[![Github Fork](https://img.shields.io/github/forks/afonsoc12/firefly-cli?logo=github)](https://github.com/afonsoc12/firefly-cli)\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA python-based command line interface for conveniently entering expenses in [Firefly III](https://www.firefly-iii.org).\n\n# Instalation\n\nThis CLI tool is available on PyPI and as a docker image.\n\n## 1. Install from PyPI\n```shell\n# Install firefly-cli from PyPI\npip install firefly-cli\n\n# Enjoy! Runs firefly-cli\nfirefly-cli\n```\n\n## 2. Docker Image\nCurrently, there are images for `x86-64`, `arm64` and `arm/v7` architectures.\n\nThey are built from python's Linux Alpine base image (`python:3.9-alpine`) which makes the application very slim (less than 20MB).\n\n| Architecture\u003cbr\u003e[![Docker Image Size](https://img.shields.io/docker/image-size/afonsoc12/firefly-cli/latest?logo=docker)](https://hub.docker.com/repository/docker/afonsoc12/firefly-cli/tags?page=1\u0026ordering=last_updated\u0026name=latest) | Tag\u003cbr\u003e[![Docker Dev Version](https://img.shields.io/docker/v/afonsoc12/firefly-cli/latest?logo=docker)](https://hub.docker.com/repository/docker/afonsoc12/firefly-cli/tags?page=1\u0026ordering=last_updated\u0026name=latest) |\n|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| x86-64 | latest |\n| arm64 | latest |\n| arm/v7 | latest |\n\nThere are also development images with the latest on master branch:\n\n| Architecture\u003cbr\u003e[![Docker Image Size](https://img.shields.io/docker/image-size/afonsoc12/firefly-cli/latest?logo=docker)](https://hub.docker.com/repository/docker/afonsoc12/firefly-cli/tags?page=1\u0026ordering=last_updated\u0026name=dev-latest) | Tag\u003cbr\u003e[![Docker Dev Version](https://img.shields.io/docker/v/afonsoc12/firefly-cli/dev-latest?logo=docker)](https://hub.docker.com/repository/docker/afonsoc12/firefly-cli/tags?page=1\u0026ordering=last_updated\u0026name=dev-latest) |\n|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| x86-64 | dev-latest |\n| arm64 | dev-latest |\n| arm/v7 | dev-latest |\n\nGetting started with firefly-cli Docker:\n```shell\n# Pull latest image\ndocker pull afonsoc12/firefly-cli:latest\n\n# Test if it is working, mount path to your firefly-cli config folder\ndocker run --rm -it \\\n -v ~/.config/firefly-cli:/config/firefly-cli \\\n afonsoc12/firefly-cli:latest\n\n# Set an alias on your .bashrc or .zshrc, so that it is more convenient to run\nalias firefly-cli=\"docker run --rm -it -v ~/.config/firefly-cli:/config/firefly-cli afonsoc12/firefly-cli:latest\"\n\n# Add some transactions!\nfirefly-cli add 5, Large Mocha, Cash, Starbucks\n```\n## 3. Bare Python\nAlternatively, you can clone the repository and install from `setup.py` or run as a python module.\n\nFrom setup.py:\n\n```shell\n# Clone the repository\ngit clone https://github.com/afonsoc12/firefly-cli.git\n\n# Go to root directory\ncd firefly-cli\n\n# Install firefly-cli\npip install .\n\n# Run firefly-cli\nfirefly-cli\n```\n\nPython module:\n\n```shell\n# Clone the repository\ngit clone https://github.com/afonsoc12/firefly-cli.git\n\n# Go to root directory\ncd firefly-cli\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run module as a script\npython -m firefly_cli\n```\n\n# Usage\nThe CLI has two modes of operation:\n\n1. In one-line command style:\n\n```shell\n$ firefly-cli add 5.2, Large Mocha, Cash, Starbucks\n```\n\n2. Command Line Interface:\n\n```bash\n$ firefly-cli\n\nCopyright 2022 Afonso Costa\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nType \"license\" for more information.\n\nWelcome to FireflyIII Command Line Interface!\nCreated by Afonso Costa (@afonsoc12)\n\n=============== Status ===============\n - URL: https://firefly.mydomain.com\n - API Token: *****iUcHo\n - Connection: OK!\n - Version: 0.1.0\n======================================\n\nType \"help\" to list commands.\n\nšŸ· āžœ\n```\n\n# Setup\nIf you run firefly-cli straight away, a warning will pop up since you haven't configured it with your FireflyIII instance.\n\nIn order to configure your Firefly III `URL` and `API_TOKEN` you have to run these two commands (you can find [here](https://docs.firefly-iii.org/firefly-iii/api/#personal-access-token) how to get your API **Personal Access Token**:\n\n```shell\n# Start CLI, well this one does not count as a command šŸ™ƒ\nfirefly-cli\n\n# Set your Firefly URL, such as https://firefly.mydomain.com\nšŸ· āžœ edit URL \u003cYOUR URL\u003e\n\n# Set your Firefly API_TOKEN\nšŸ· āžœ edit API_TOKEN \u003cYOUR API TOKEN\u003e\n```\n\nAfter entering these values, firefly-cli will automatically refresh API connection. At any point, you can trigger a connection refresh:\n\n```shell\n# Refreshes API connection\nšŸ· āžœ refresh\n```\n\nAlternatively, you can create a `firefly-cli.ini` file and place it in `$XDG_CONFIG_HOME/firefly-cli/firefly-cli.ini` with the following content:\n```yaml\n[API]\nurl = https://firefly.yourdomain.com\napi_token = eyXXX\n```\n**Note:** If `$XDG_CONFIG_HOME` is not set, it defaults to `$HOME/.config/firefly-cli/firefly-cli.ini`\n\nfirefly-cli can override this behaviour and read/write from the file specified by the environment variable `FIREFLY_CLI_CONFIG`.\n\n# Commands\nThe scope of this CLI is to enter expenses in a comma-separated style.\n\nStarting in **[v0.1.0](https://github.com/afonsoc12/firefly-cli/releases/tag/v0.1.0)**, it now supports adding all possible transaction fields using optional arguments (e.g. `--source-name \"Bank HSBC\"`).\nThe comma-separated arguments (aka positional arguments) are maintained for backwards-compatibility, but optional arguments will **always** override the comma-separated ones\n\nSummary of the available commands:\n\n| Command | Description |\n|-----------------|-----------------------------------------------------------------------------------------------------------------------------|\n| `help` | Shows the available commands. |\n| `accounts` | Shows budgets information (UI unpolished). |\n| `add` | Adds a transaction to FireflyIII (See `add` section). |\n| `budgets` | Shows budgets information (UI unpolished). |\n| `edit` | Edits URL and API_TOKEN parameters. Type edit [URL/API_TOKEN] \u003cVALUE\u003e` to configure firefly-cli with your Firefly instance. |\n| `exit` | Exits the CLI tool. |\n| `help` | Shows available commands. Type `help [command]` to display information about that command. |\n| `license` | Shows License information. |\n| `refresh` | Refreshes API connection. |\n| `version` | Shows firefly-cli version. |\n\n## Adding a transaction\nThe 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`.\n\nBy default, every transaction is a **withdrawal** and is placed with the current date and time.\nYou 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`.\n\nThe comma-separated fields available are the following:\n\n`Amount, Description , Source account, Destination account, Category, Budget `\n\n**The first four fields can NEVER be omitted!**\n\n### Examples\n\n```shell\n# These four fields are mandatory\n# Mandatory fields: amount, description, source_account, destination_account\nšŸ· āžœ add 5, Large Mocha, Cash, Starbucks\n\n# Don't need to be exclusively comma-separated fields, as long as they are specified\nšŸ· āžœ add --amount 5 --description \"Large Mocha\" --source-name Cash --destination-name Starbucks\n\n# Or a mixture of comma-separated and optional arguments\nšŸ· āžœ add 5, Large Mocha --source-name Cash --destination-name Starbucks\n\n# Remember: optional arguments ALWAYS override comma-separated ones\nšŸ· āžœ add 5, Large Mocha, Cash, Starbucks --source-name \"Bank HSBC\"\n# will create a transaction whose source is \"Bank HSBC\" and NOT \"Cash\"\n\n# You can skip specfic fields by leaving them empty\nšŸ· āžœ add 5, Large Mocha, Cash, Starbucks, , Morning Coffees\n# sets the budget to \"Morning Coffees\" and skips the category\n```\n\n## Credits\n\nCopyright 2022 Afonso Costa\n\nLicensed under the [Apache License, Version 2.0](https://github.com/afonsoc12/firefly-cli/blob/master/LICENSE) (the \"License\")\n\nFireflyIII logo extracted from the official [FireflyIII website](https://www.firefly-iii.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafonsoc12%2Ffirefly-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafonsoc12%2Ffirefly-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafonsoc12%2Ffirefly-cli/lists"}