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).
• 🤖 Telegram Bot: Optional integration to securely interact with Sigma via Telegram using standard CLI commands.

Installation

Sigma requires Python 3.10 or higher.

# Core CLI only
pip install sigma-finance

# With Telegram Bot integration
pip install "sigma-finance[telegram]"

First-run Setup

Once installed, initialize your database and create your first account:

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

Telegram Bot

To run Sigma as a background bot, configure your credentials and launch the daemon:

sgm bot setup   # Configure bot token and allowed users
sgm bot run     # Launch the daemon

For Docker, systemd, or launchd setup details, see the Telegram Bot Deployment Guide.

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 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).
sgm bot setup	Configure the Telegram Bot credentials.
sgm bot run	Start the Telegram Bot event loop.

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 entrypoints
  • telegram_bot.py — Telegram bot integration
  • 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.