sigma-finance 0.4.0

Sigma CLI finance tracker

Sigma (sgm)

Sigma is a fast, CLI-first personal finance tracker designed for local use. It focuses on rapid transaction logging, simple account management, and auditable snapshots through a "rendering" cycle.

Why Sigma?

Most finance trackers are either too complex or require too many clicks. Sigma is built for users who live in the terminal and want to:

• Log quickly: Record expenses, income, and transfers with minimal keystrokes.
• Audit with ease: Use the render command to verify and clear your pending movements into historical snapshots.
• Stay local: Your data stays on your machine in a lightweight SQLite database.
• See the big picture: Rich terminal tables provide instant clarity on your balances and credit availability.

Features

• ⚡ Fast Logging: Simple commands for exp (expense), inc (income), and tr (transfer).
• 🏦 Account Management: Support for both Debit and Credit accounts with rolling credit limit tracking.
• 🔄 Rendering Cycle: Mark movements for review and "render" them into your history once verified.
• 📊 Rich Interface: Beautifully formatted tables powered by Rich.
• 📜 Audit Log: Full history of movements and render snapshots.
• 🌐 Web Dashboard: Modern, minimalist local web client (sgm web).
• 🖥️ Desktop App: Native macOS window container for the web client (sgm app).

Installation & Setup

🖥️ macOS Standalone Application (Recommended)

Sigma is distributed primarily as a standalone macOS application. You do not need to install Python or use the terminal to get started.

1. Download the app: Get the latest Sigma.dmg or Sigma.app.zip from GitHub Releases.
2. Install: Drag Sigma to your /Applications folder.
3. Launch: Double-click Sigma.app to open the native application window.
4. Onboarding: On your first launch, the app will automatically initialize. An interactive onboarding welcome screen will guide you to set up your primary cash account or import a previous backup ZIP.
5. Optional CLI Setup: On startup, the app automatically symlinks the sgm command-line executable into your path (at /usr/local/bin/sgm or ~/.local/bin/sgm). You can open your terminal and run sgm status to start using the CLI alongside the app!

💻 Command-Line Interface (CLI) & Developer Setup

For developers or terminal-only users, Sigma can be installed as a Python package. It requires Python 3.10 or higher.

# Install core CLI only
pip install sigma-finance

# Or install with native desktop window support (macOS)
pip install "sigma-finance[desktop]"

First-run CLI setup: If you are using the CLI standalone, initialize your database and configuration wizard:

sgm start

Usage

Core Workflow

1. Check your status:

   sgm status
   

2. Log an expense:

   # Usage: sgm exp <amount> <description> <mark_for_render: yes|no> [account_id] [date]
   sgm exp 5000 "Lunch" yes wallet 2026-05-20
   

3. Log income:

   sgm inc 2500000 "Salary" no bci
   

4. Transfer between accounts:

   sgm tr bci wallet 50000
   

5. Render marked movements:

   # Sums marked items, logs to history, and clears marks.
   sgm render
   

Web Dashboard

To launch the local web interface:

sgm web         # Launches the local dashboard in your browser

Desktop App

To run Sigma in a native macOS application window instead of your web browser, install the desktop package and launch it:

sgm app

Command Reference

Command	Description
sgm status	Show balances, credit limits, and marked totals.
sgm log [limit]	List recent movements (default: 15).
sgm history	View previous render results.
sgm acc list	List all accounts and their details.
sgm config	Configure default accounts for faster logging.
sgm web	Start the local web dashboard server.
sgm app	Launch the native macOS desktop app window.
sgm export	Export all data to a ZIP file with CSV tables.
sgm delete <id>	Remove a record by its unique ID (e.g., m-1).

For a complete reference of all available commands and their arguments, please refer to the Detailed CLI Usage Guide.

Development

We use Makefile for common development tasks.

# Clone the repository
git clone https://github.com/fzunigam/sigma
cd sigma

# Install in editable mode with dev dependencies
make install

# Run tests
make test

# Run linter
make lint

Project Structure

• src/sgm/ — Core Python package
  • cli.py — Typer-based CLI command routing
  • app_launcher.py — GUI Application runner & CLI symlink checker
  • cli_launcher.py — CLI Application runner for the bundled binary
  • infrastructure/ — database, persistence and config management (database.py, user_config.py)
  • interface/ — terminal UI, banners and web server glue
  • interface/web/ — lightweight web server and static assets for the dashboard
• web/ — Next.js web client (React + Tailwind) and frontend sources
• docs/ — architecture, guides, deployment notes, and coding conventions
• tests/ — test suites (smoke, integration, unit)
• assets/ — images and demo assets (GIFs, screenshots)

License

Sigma is licensed under the MIT License.

Acknowledgments

• Typer for the CLI framework.
• Rich for the beautiful terminal output.