ffiii-tui

⚠️ Warning: This project is in early development and may not be fully functional.

A terminal user interface (TUI) for Firefly III personal finance manager. Manage your finances directly from the terminal with an intuitive interface.

✨ Features

• 📊 View and manage transactions, assets, categories, expenses, and revenue accounts
• 🔍 Search and filter transactions
• 💰 Real-time insights with account balances and spending analysis
• 📝 Create transactions directly from the terminal interface
• 🎨 Clean TUI built with Charm's Bubble Tea framework

Transaction Management

• Create new transactions with guided forms
• View transaction details and splits
• Navigate between different time periods
• Filter by account, category, or search terms

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Access to a Firefly III instance
• Firefly III API key (How to get an API key)

Installation

Option 1: Using parm (Recommended)

parm is a cross-platform binary package manager for GitHub releases. This is the easiest way to get started:

1. Install parm (if not already installed):

   curl -fsSL https://raw.githubusercontent.com/alxrw/parm/master/scripts/install.sh | sh

2. Install ffiii-tui:

   parm install ewok/ffiii-tui

3. Initialize configuration:

   ffiii-tui init-config -k YOUR_API_KEY -u https://your-firefly-instance.com/api/v1

4. Run the application:

   ffiii-tui

To update ffiii-tui later, simply run:

parm update ewok/ffiii-tui

Option 2: Clone and build from source

1. Clone and build:

   git clone https://github.com/yourusername/ffiii-tui
   cd ffiii-tui
   go mod tidy
   go build

2. Initialize configuration:

   ./ffiii-tui init-config -k YOUR_API_KEY -u https://your-firefly-instance.com/api/v1

3. Run the application:

   ./ffiii-tui

📋 Usage

Basic Commands

# Start with default config
./ffiii-tui

# Use custom config file
./ffiii-tui --config path/to/your/config.yaml

# Pass API credentials directly
./ffiii-tui -k YOUR_API_KEY -u https://your-firefly-instance.com/api/v1

# Initialize config file
./ffiii-tui init-config

⚙️ Configuration

The application uses a YAML configuration file. Generate one with:

./ffiii-tui init-config

Configuration Options

# Required Firefly III API settings
firefly:
  api_key: YOUR_API_KEY # Your Firefly III API token
  api_url: https://your-instance.com/api/v1 # API endpoint URL

# Optional UI settings
ui:
  full_view: false # Full-width transaction view

# Optional logging
logging:
  file: "ffiii-tui.log" # Log file path

🏗️ Development

Project Structure

ffiii-tui/
├── cmd/                # CLI commands
├── internal/
│   ├── firefly/        # Firefly III API client
│   ├── ui/             # TUI components
│   └── logging/        # Logging utilities
├── config.yaml         # Configuration file
└── main.go             # Entry point

Building from Source

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Build
go build -o ffiii-tui

# Run with debug logging
./ffiii-tui --debug

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

TODO/Roadmap

• Create new transactions
• Edit existing transactions
• Delete transactions
• Create accounts, categories
• Edit accounts, categories
• Delete accounts, categories
• Advanced filtering and search
  • Not only in current period
• Budget management
• Piggy banks
• Subscriptions
• Reporting and charts

📦 Dependencies

Package	Purpose
Bubble Tea	TUI framework
Bubbles	TUI components
Lip Gloss	Styling
Cobra	CLI framework
Viper	Configuration management
Zap	Logging

📄 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.