greed

README

GREED

Table of Contents

• Overview
  • Server Features
  • CLI Features
• Demo
• System Requirements
• Installation Options
• Changelog
• Usage
• Quick Start
• To-Do List
• Contributing & Issues
  • Known Issues

Overview

Greed is a financial application written almost entirely in Golang, used to view/track data easily across financial institutions/accounts. It utilizes the third-party API Plaid to connect your account with your financial institutions, and obtain your account and transaction history. This data can then be viewed in a user friendly format, which can be used to track past expenditures and plan future ones.

Since this app utilizes paid Plaid functions, and is not intended for widespread use, users are restricted in a 'demo' mode, in the number of calls they can make to certain server endpoints, specifically those that talk to Plaid. Users are limited to 5 calls to update/sync their financial data.

Server Features

• RESTful API
• Endpoints
• Postgres database
• No storing of sensitive personal or financial information, with the exception of Plaid Access Tokens, which are encrypted at rest
• JWT authentication
• Integration with financial data aggregator Plaid
• Plaid webhooks, allowing notification of users of updates available for their items
• Account-email verification utilizing SendGrid

CLI Features

• Cobra-based CLI tool
• CLI Commands
• Client SQLite database
• Auto-update/syncing data upon user login
• Basic reporting of account information for financial institutions
• 24 months of account financial history
• In-depth transaction history reporting
  • Utilizing paginated tables in terminal
  • Extensive sorting through amount, date, merchant, etc.
  • Allows summary reporting as well
    • ex. All transactions summed, showing count and total amount for each merchant, for each month
    • ex. All transactions for merchant 'A' for month 'X' summed, showing count, total amount, dates
    • ex. All transactions for merchant 'A' summed over full 24-month history, showing count, total amount
• Income/Expense viewing
  • View Income vs. Expenses per account
  • Viewable in tables and graphs
• Export data into a CSV file

Demo

Below are some quick demonstrations of some core features:

1. User Registration

2. Syncing Your Accounts

3. Viewing Transactions & Summary Reports

Standard Transaction View:

System Requirements

• No dependencies for binary installation
• Docker (for Docker installation)
• Go 1.24+ (for source installation)

Installation Options

1. Download Binary (Recommended)

   • Download from Releases

   • Make it executable and run:

     • Linux:

     # Download greed-cli-linux-amd64
     chmod +x greed-cli-linux-amd64
     ./greed-cli-linux-amd64 ping
     
     # Optional: Rename for easier use
     mv greed-cli-linux-amd64 greed
     ./greed register ExampleUser
     

     • Windows:

     # Download greed-cli-windows-amd64.exe
     # No chmod needed, just run directly
     # Cd into download directory (ex. Downloads)
     cd .\Downloads\
     .\greed-cli-windows-amd64.exe ping
     
     # Rename in file explorer, or in command line
     ren greed-cli-windows-amd64.exe greed.exe
     .\greed.exe register ExampleUser
     

     Windows Users: It's recommended to use Windows Terminal for the best experience:

     • Download from Microsoft Store or GitHub releases
     • Full support for colors, tables, and interactive features
     • Use default PowerShell tab

     If Windows Terminal isn't available: Use Command Prompt (cmd.exe) as a fallback. Powershell will crash with paginated table views.

   Windows Security Warning

   Windows Defender may flag the executable as suspicious. This is a false positive common with Go applications. To resolve:

   1. Windows Defender: Click "More info" → "Run anyway"
   2. Chrome: Click "Keep" on the download warning
   3. Add exception: Add the download folder to Windows Defender exclusions

   The source code is available for inspection, and you can build from source if preferred.

2. Docker

   • Have Docker installed
   • Pull the image:

   docker pull jmsguy/greed-cli
   

   • Create directories:

     • Linux:

     mkdir -p ~/.config/greed
     

     • Windows:

     mkdir "$env:USERPROFILE\.config\greed"
     

   • Add an alias for easy input:

     • Linux/macOS:

     alias greed='docker run -it -p 8080:8080 --user $(id -u):$(id -g) -e HOME=/home/user -v ~/.config/greed:/home/user/.config/greed jmsguy/greed-cli'
     

     • Windows (PowerShell):

     function greed { docker run -it -p 8080:8080 -v "$env:USERPROFILE\.config\greed:/root/.config/greed" jmsguy/greed-cli $args }
     

     • Docker flags breakdown:

       • '-it': Run the docker image in an interactive terminal session, for getting input after the original command
       • '-p 8080:8080': Maps the container's port 8080 to host, allowing the CLI to open a temp server to listen for Link callback
       • '--user': Runs docker container as your user instead of root, granting user correct read/write permissions for volume
       • '-v': Mounts a docker volume to the image, allowing for client-side database use and export functionality

     • To make the alias permanent, add it to your shell profile:

       • Linux/macOS:

       echo "alias greed='docker run -it -p 8080:8080 --user $(id -u):$(id -g) -e HOME=/home/user -v ~/.config/greed:/home/user/.config/greed jmsguy/greed-cli'" >> ~/.bashrc
       source ~/.bashrc
       

       • Windows PowerShell:

       Add-Content $PROFILE "function greed { docker run -it -p 8080:8080 -v `"`$env:USERPROFILE\.config\greed:/root/.config/greed`" jmsguy/greed-cli `$args }"
       . $PROFILE
       

   • Run commands!

   greed register ExampleUser
   greed login ExampleUser
   

   • Note for Docker users: Link opening is not supported in containers. The CLI will display the link for you to copy and paste into your browser.

3. Install directly

   • Requires Go

   go install github.com/jms-guy/greed@latest
   greed --help
   

4. Clone repo

   • Requires Go

   git clone https://github.com/jms-guy/greed
   cd greed
   go build
   ./greed --help
   

Changelog

See the Changelog

Usage

• List of CLI commands found here
• Typical user interaction will begin with:
  • Register
  • Login
  • Fetch
• Help can be found with the command:

greed --help

Quick Start

# Register and connect your bank
greed register myusername
greed login myusername
greed fetch itemname

# View your financial data
greed get accounts
greed get txns "Account Name"
greed export "Account Name"

To-Do List

• CLI tests + integration tests
• Recurring transaction detection
• Custom transaction tags and filtering
  • Tag certain merchants/transactions with custom labels (fixed expense, variable expense, tax-deductible, vacation fund, etc.)

Contributing & Issues

To contribute, clone the repo as described above in Installation Options. Please fork the repository and open a pull request to the main branch. If you have an issue, please report it here.

Known Issues

• Balance values are off in credit card tables, uses calculations for getting historical balances of a debit account
• Only partial support for attaching multiple financial institutions per user