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

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.