devledger

README

DevLedger

A local-first CLI tool for tracking and splitting shared infrastructure costs among developer teams. No cloud, no setup - runs entirely on your machine.

Installation

Option 1 - Install directly

go install github.com/ChaitanyaSai-Meka/devledger@latest

If devledger is not found after install, make sure Go's bin directory is on your PATH:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify the install:

which devledger
devledger --help

Option 2 - Build from source

git clone https://github.com/ChaitanyaSai-Meka/devledger
cd devledger
go build -o devledger .
sudo mv devledger /usr/local/bin/

Verify the install:

which devledger
devledger --help

Quick Start

# Create users
devledger user create --username "alice"
devledger user create --username "bob"
devledger user create --username "charlie"

# Create a group and add members
devledger group create --groupname "backend-team"
devledger group add-member --groupname "backend-team" --username "alice"
devledger group add-member --groupname "backend-team" --username "bob"
devledger group add-member --groupname "backend-team" --username "charlie"

# Add an expense
devledger expense add --groupname "backend-team" --description "AWS Bill" --amount "30.00" --paidby "alice"

# View balances
devledger balance group --groupname "backend-team"

# Get suggested settlements
devledger balance simplify --groupname "backend-team"

Commands

Users

devledger user create --username <name>
devledger user delete --username <name>
devledger user list
devledger user groups --username <name>

Groups

devledger group create --groupname <name>
devledger group delete --groupname <name>
devledger group list
devledger group members --groupname <name>
devledger group add-member --groupname <name> --username <name>
devledger group remove-member --groupname <name> --username <name>

Expenses

devledger expense add --groupname <name> --description <desc> --amount <amount> --paidby <name>
devledger expense list --groupname <name>
devledger expense list-by-user --username <name>
devledger expense detail --expenseid <id>
devledger expense delete --expenseid <id>
devledger expense settle --expenseid <id> --username <name>
devledger expense unsettled --username <name>

Balances

devledger balance group --groupname <name>
devledger balance simplify --groupname <name>

How it Works

CLI commands
    ↓ HTTP calls
REST API (localhost:38080)
    ↓
Service Layer (business logic)
    ↓
Repository Layer (DB queries)
    ↓
SQLite (devledger.db)

For each devledger ... command you run, the local server starts automatically, handles that command's work, and then shuts down when the command finishes.

Amount Format

All amounts are entered in rupees. Values with 0-2 decimal places are typical, and values with additional decimal places are accepted and rounded to the nearest paise:

--amount "30.00"    # ₹30.00
--amount "1500"     # ₹1500.00
--amount "99.99"    # ₹99.99
--amount "10.999"   # rounded to ₹11.00

Internally stored in paise to avoid floating-point precision issues.

Future Enhancements

• Custom expense splits (unequal amounts)
• Partial payment tracking
• Edit expense description and amount
• Database migrations using golang-migrate
• Idle timeout - automatically shut down the server after inactivity
• Multi-currency support

Tech Stack

• Language - Go
• Router - Chi
• CLI - Cobra
• Database - SQLite (modernc.org/sqlite - pure Go, no CGo)
• Money parsing - shopspring/decimal