Om handledningen

Detta är den praktiska användarhandledningen för Larin och den auktoritativa motorn ledgerctl. Den följer det aktuella kodläget och beskriver både den första skarpa starten och den löpande vardagsanvändningen.

ledgerctl är inte ett enda monolitiskt bokföringsprogram. Det är en samlad ingång till flera delsystem som delar samma arbetsyta och samma hLedger-data:

bankens CSV
    │
    ▼
importmotor ──► routing och dedupe ──► finance.journal
                                         ▲
Purchase API / ledgerctl add ────────────┘
                                         │
                     audit / report / reconcile
                                         │
                                         ▼
                           årsarkiv + verifiering

finance.journal + budgetjournaler ──► all.journal
                                         │
                status / history / analytics / doctor
                                         │ JSON
                      ┌──────────────────┼──────────────────┐
                      ▼                  ▼                  ▼
                 Larin CLI          Emacs UI          statisk webb

Den viktigaste uppdelningen är:

• finance.journal innehåller verkliga bank- och manuella transaktioner.
• Budgetlagret använder separata virtuella konton under budget:*.
• Varje verklig expenses:*-post måste tillhöra exakt ett namngivet kuvert.
• Reservkuvertet Att kategorisera fångar okända utgifter utan att göra dem osynliga för budgeten.
• all.journal inkluderar både verkligheten och budgetlagret.
• Larin CLI, Emacs och webben är konsumenter av ledgerctl:s JSON-kontrakt.
• Konsumenterna ska inte själva tolka journalfiler eller räkna om ekonomiska beslut.
• larin är den rekommenderade vardagsklienten i terminalen; ledgerctl är den auktoritativa motorn och integrationsytan.

Läsordning

1. Introduktion till kuvertbudgetering — varför kuvert används och hur de förändrar synen på banksaldot.
2. Bankimport och arbetsyta — öppningssaldo, bootstrap, konfiguration och CSV-import.
3. Routes och mottagardatabas — hur återkommande mottagare automatiseras.
4. Manuella transaktioner — larin purchase och Purchase API.
5. Audit, report och reconcile — kontroll och rapportering.
6. Årsarkiv, checksummor, GPG och Git-förankring.
7. Kuvertbudget — kommandon och administration ovanpå hLedger.
8. Doctor och felsökning — miljö- och datakontroller.
9. JSON-konsumenter, Emacs och statisk webb.
10. Larin terminalklient — TAB-komplettering, köp och administration.
11. Kommandoreferens — kompakt uppslagsverk.

Förutsättningar

Grundfunktionerna förutsätter normalt att dessa program finns installerade:

• Bash,
• Python 3.10 eller senare,
• GNU Make eller kompatibelt make,
• hLedger 1.50.4 eller senare i 1.x-serien för rapporter, reconcile och budgetfunktioner.

Följande är valfria beroenden:

• rapidfuzz förbättrar förslagen i suggest-routes,
• GnuPG behövs endast för GPG-signering eller strikt signaturverifiering,
• Git behövs för extern arkivförankring.

Kontrollera installationen med:

ledgerctl doctor

Kom igång på fem minuter

mkdir -p ~/budget
cd ~/budget

ledgerctl init --with-seed
ledgerctl doctor

cp /sökväg/till/swedbank-export.csv imports/
ledgerctl audit imports/swedbank-export.csv
ledgerctl suggest-routes imports/swedbank-export.csv
ledgerctl import imports/swedbank-export.csv
ledgerctl report bal

Om du även vill använda kuvertbudgeten:

ledgerctl budget init
larin kuvert add
larin doctor
larin status

För avancerad konfiguration går det fortfarande att redigera budget/envelopes.conf och därefter köra ledgerctl budget regen-auto, men den användarvänliga vardagsvägen är Larin CLI eller Emacs-administrationen.

Säkerhetsmodell

ledgerctl försöker göra farliga handlingar uttryckliga:

• Import gör en preflight och stoppar vid okända mottagare.
• Import skriver genom att lägga till poster; den ersätter inte journalen tyst.
• Möjliga dubbletter mot manuella poster ger en varning men tas aldrig bort automatiskt.
• Budget- och adminmutationer är preview som standard och kräver en aktuell revision; batchändringar använder dessutom digest för att binda apply till exakt den granskade planen.
• Larin CLI och Emacs pratar endast JSON med ledgerctl och ska aldrig öppna arbetsytans datafiler direkt.
• Kuverttäckningen valideras före import och före budgetmutationer.
• Årsarkivering är dry-run som standard och kräver --commit för att ändra filer.
• Årsarkiv får SHA-256-manifest och kan GPG-signeras.
• Extern Git-förankring skickar endast manifestet och arkivinformationen, inte bankens CSV eller journalen.
• Doctor-kommandon är skrivskyddade och reparerar ingenting automatiskt.

Rekommenderad vardagsrytm

Vid ett köp innan bankexporten finns

larin purchase --merchant ueb --amount 299 --note "Bok"

Eller öppna den interaktiva klienten och använd TAB-komplettering:

larin

Där ueb är en definierad shortcut för English Bookshop.

Posten blir pending. När bankens CSV senare importeras varnar importen om den ser en sannolik motsvarighet. Granska och ta bort den manuella posten själv om det är samma köp.

När en ny CSV har hämtats

ledgerctl audit imports/2026-07.csv
ledgerctl suggest-routes imports/2026-07.csv

# När kuvertbudgeten är aktiv:
ledgerctl suggest-envelopes
ledgerctl budget coverage --scope routes

ledgerctl import imports/2026-07.csv --all
ledgerctl reconcile
ledgerctl report month
larin status

Inför ett månadsskifte

ledgerctl budget doctor
ledgerctl budget status --month 2026-07
ledgerctl budget sweep-month

Granska previewn och verkställ med den revision som kommandot visar. Se kuvertbudgetguiden för hela flödet.

När ett år är färdigt

ledgerctl reconcile
ledgerctl audit
ledgerctl budget doctor
ledgerctl archive 2026
ledgerctl archive 2026 --commit --sign
ledgerctl verify 2026 --require-signature --anchor

Hjälp i terminalen

Både den användarvänliga klienten och motorn har hjälp:

larin --help
larin purchase --help
larin merchant add --help
larin kuvert add --help

ledgerctl --help
ledgerctl import --help
ledgerctl add --help
ledgerctl budget --help
ledgerctl budget move --help