Syfte

larin är den användarvänliga terminalkonsumenten för Larin. Den använder ledgerctl:s versionsmärkta JSON-API och har ingen egen ekonomisk motor.

Det betyder att larin:

• inte läser eller skriver journalfiler direkt,
• inte tolkar merchant-db.json eller envelopes.conf själv,
• inte räknar om budgetsaldo eller invariant,
• alltid låter ledgerctl göra validering, preview och apply,
• kan ge en enklare terminalupplevelse utan att skapa en andra sanningskälla.

användare
   │
   ▼
larin ── JSON subprocess API ──► ledgerctl ──► hledger + arbetsyta

Terminalklienten kompletterar de andra konsumenterna:

Starta klienten

Kör från en katalog som innehåller ledgerctl.conf:

cd ~/budget
larin

Om larin körs direkt ur projektträdet:

~/Projects/Larin/bin/larin

Du kan också ange arbetsytan explicit:

larin --workspace ~/budget status

Sökordningen för arbetsytan är:

1. --workspace KATALOG,
2. miljövariabeln LARIN_WORKSPACE,
3. närmaste ledgerctl.conf uppåt från aktuell katalog.

Själva upptäckten och valideringen görs genom ledgerctl workspace locate --format json. När arbetsytan är fastställd installerar Larin ett runtime-skydd som blockerar direkt filåtkomst i arbetsytan. Klienten kan därför inte råka ta en genväg förbi JSON-kontrakten.

ledgerctl-programmet kan väljas med --ledgerctl eller LARIN_LEDGERCTL. När klienten körs ur källträdet används normalt projektets bin/ledgerctl automatiskt.

Interaktiv huvudprompt

larin utan underkommando öppnar en kommandoprompt:

Larin
=====
  status      Visa budget
  översikt    Förstå vart pengarna gick
  köp         Registrera köp
  doctor      Kör Budget Doctor
  merchants   Lista merchants
  merchant+   Lägg till merchant
  kuvert      Lista kuvert
  kuvert+     Lägg till kuvert
  avsluta     Avsluta

Skriv ett kommando; TAB kompletterar.
larin>

Skriv början av ett kommando och tryck TAB:

larin> sta<TAB>
larin> status

Både svenska och engelska namn fungerar. Sifferkommandon finns kvar för muskelminne, men ordkommandon med TAB-komplettering är den rekommenderade vägen.

Visa budgetstatus

larin status
larin status --month 2026-07
larin budget status --month 2026-07

larin status utan månad visar status för alla perioder som motorn returnerar. Rubriken visas då som Alla perioder. Med --month visas en månadsspecifik översikt.

Det korta aliaset finns kvar:

larin budget --month 2026-07

budget fungerar alltså både som statusalias och som kommandogrupp med status och doctor.

Belopp, saldo och ekonomiska tillstånd kommer direkt från ledgerctl budget status --format json. Terminalklienten räknar inte om siffrorna.

Förstå vart pengarna gick

larin insights --month 2026-07 --months 12
# Svenskt alias:
larin översikt --month 2026-07

Detta är Larins samlade ekonomiöversikt. Fas 3 visar:

• inkomster, utgifter, netto och antal köp för vald månad,
• rangordnade utgifter per kuvert,
• största merchants med antal köp och genomsnitt,
• utgiftstrend för de senaste månaderna,
• skillnaden mot föregående månad,
• skillnaden mot medianen för upp till sex tidigare månader,
• vilka kuvert som ligger över budget och med hur mycket,
• hur många köp och hur stora belopp som ligger i fyra köpintervall,
• datatäckning för utgifter utanför kuvert och okända merchants,
• merchants som återkommer under minst tre månader,
• möjliga stabila månadsbetalningar markerade som kandidater,
• hur månadens positiva köp fördelas mellan stabilt återkommande, rörligt återkommande och övriga köp.

Alla belopp, andelar och rangordningar kommer från ledgerctl budget insights --format json. Terminalklienten använder bara Unicode- eller ASCII-staplar för presentation. Jämförelser, medianer och budgetavvikelser och återkommande mönster räknas alltid av ledgerctl.

En möjlig abonnemangskandidat är inte ett automatiskt påstående. Larin visar vilka signaler som finns — månadsrytm, stabilt belopp, en betalning per månad och stabil betalningsdag — så att du själv kan granska kostnaden.

Kör Budget Doctor

larin doctor
larin budget doctor

Båda formerna visar samma rapport. larin budget utan underkommando visar fortfarande budgetstatus; doctor är ett riktigt underkommando i budgetgruppen.

Kommandot visar den skrivskyddade Budget Doctor-rapporten. Om rapporten innehåller health-check-fel bevarar larin motorns felstatus i processens exitkod. En rapport med fel är alltså fortfarande en korrekt diagnostikrapport.

Registrera ett köp

Interaktivt

larin purchase

eller:

larin köp

Klienten frågar efter:

• merchant,
• belopp,
• datum,
• valfri anteckning,
• pending eller cleared.

Merchantprompten har TAB-komplettering över mänskliga shortcuts och visningsnamn från Merchant API:t:

Merchant (shortcut eller namn, TAB kompletterar): ue<TAB>

Bankalias används endast av importmotorn och visas inte som mänskliga kommandon.

Direkt form

larin purchase \
  --merchant ica \
  --amount 243,50 \
  --date 2026-07-22 \
  --note "Matinköp"

Merchant får vara:

• merchant-id,
• shortcut,
• exakt visningsnamn.

Standard är pending. Använd --cleared när köpet redan är verifierat:

larin purchase --merchant ica --amount 243,50 --cleared

Preview och apply

Varje köp går genom samma säkra livscykel:

bygg request
   │
   ▼
Purchase API preview
   │ visa journalpost, budgetpåverkan och dubbletter
   ▼
användarbekräftelse
   │
   ▼
samma request + request_digest + revision + apply

Visa endast preview:

larin purchase \
  --merchant ica \
  --amount 243,50 \
  --preview-only

Verkställ den visade previewn utan en andra terminalfråga:

larin purchase \
  --merchant ica \
  --amount 243,50 \
  --yes

--yes hoppar inte över preview. Det hoppar bara över den efterföljande bekräftelsefrågan.

Lista merchants

larin merchants
larin merchant list
larin handlare lista

Listan hämtas från Merchant API:t och visar normalt namn, shortcut, standardkonto och permanent merchant-id.

Skapa en merchant

Interaktivt

larin merchant add

Svenska alias:

larin handlare skapa

Klienten frågar normalt efter:

• visningsnamn,
• standardkonto under expenses:,
• permanent merchant-id,
• bankalias,
• shortcuts,
• valfri landskod, webbplats och anteckning.

Kända expense-konton erbjuds med TAB-komplettering. Merchant-ID föreslås från namnet men kan granskas innan preview.

Direkt form

larin merchant add \
  --name "Uppsala English Bookshop" \
  --category expenses:hobbies:books \
  --shortcut ueb \
  --alias "THE ENGLISH BOOK" \
  --country SE

--alias och --shortcut får upprepas:

larin merchant add \
  --name "Exempelbutik" \
  --category expenses:shopping:other \
  --alias "EXEMPELBUTIK UPPSALA" \
  --alias "EXEMPELBUTIK WEB" \
  --shortcut ex \
  --shortcut exempel

Visa endast Merchant API:ts preview:

larin merchant add \
  --name "Exempelbutik" \
  --category expenses:shopping:other \
  --preview-only

Vid apply skickas exakt samma request tillbaka med den revision som motorn returnerade i previewn.

Lista kuvert

larin envelopes
larin envelope list
larin kuvert lista

Listan kommer från Envelope API:t och visar namn, kuvert-id och budgetkonto.

Skapa ett kuvert

Interaktivt

larin kuvert add

eller:

larin envelope add

Du anger:

• visningsnamn,
• permanent kuvert-id,
• ett eller flera expenses:-konton.

I den interaktiva prompten anges ett konto i taget. TAB kompletterar konton som motorn redan exponerar, men ett nytt expenses:-konto får skrivas fritt. Tom rad avslutar kontolistan efter minst ett konto.

Direkt form

larin kuvert add \
  --label "Kläder" \
  --id clothes \
  --account expenses:shopping:clothes \
  --account expenses:clothing

--account får upprepas.

Visa endast preview:

larin kuvert add \
  --label "Kläder" \
  --id clothes \
  --account expenses:shopping:clothes \
  --preview-only

Envelope API:t bygger en staged version av envelopes.conf och auto.journal och kör konfigurations- och hledgerkontroller innan något får skrivas. CLI:t redigerar aldrig filerna självt.

Uppdatera ett kuvert

Lägg till konton i ett befintligt kuvert:

larin envelope update groceries \
  --add-account expenses:restaurants \
  --add-account expenses:fika

Du kan även byta etikett eller ta bort kontorötter:

larin envelope update groceries \
  --label "Mat och restaurang" \
  --remove-account expenses:food \
  --preview-only

Konto-flaggorna får upprepas. Ledgerctl validerar den slutliga kuvertmodellen, regenererar auto.journal i staging och publicerar båda filerna atomiskt.

För många otäckta kategorier används motorns interaktiva batchassistent:

ledgerctl suggest-envelopes

Den har TAB-komplettering och en enda avslutande preview; Larin CLI behöver inte själv läsa routes eller kuvertfiler för att ge denna hjälp.

Användning i script

Direktkommandona kan användas utan huvudprompt:

larin --workspace ~/budget status --month 2026-07
larin --workspace ~/budget merchants
larin --workspace ~/budget kuvert lista

För mutationer bör script normalt använda --preview-only först och därefter ett uttryckligt --yes endast när previewn redan är granskad i det avsedda flödet.

Utdata är avsedd för människor. Program som behöver stabilt maskinformat ska anropa ledgerctl --format json direkt.

Containerdemo

Starta Larin CLI mot en helt påhittad och temporär arbetsyta:

./demo/demo.sh cli

Direktkommandon:

./demo/demo.sh cli status --month 2026-07
./demo/demo.sh cli doctor
./demo/demo.sh cli merchants
./demo/demo.sh cli purchase
./demo/demo.sh cli merchant add --preview-only
./demo/demo.sh cli kuvert add --preview-only

Ändringarna försvinner när containern avslutas.

Felsökning

Ingen arbetsyta hittas

Kontrollera:

pwd
find .. -name ledgerctl.conf -print

Ange sedan arbetsytan explicit:

larin --workspace /sökväg/till/budget status

ledgerctl hittas inte

command -v ledgerctl
larin --ledgerctl ~/Projects/Larin/bin/ledgerctl status

TAB-komplettering saknas

TAB-komplettering kräver en interaktiv terminal och Pythons readline-modul. Klienten fungerar fortfarande med vanlig inmatning om readline inte finns.

Ett API-kontrakt avvisas

Kör motsvarande ledgerctl-kommando med --format json och granska den råa utdatan. Konsumenten ska stoppa i stället för att gissa när ett versionsmärkt kontrakt inte matchar förväntningarna.

Tester

consumers/cli/run-tests.sh

Testerna använder en falsk ledgerctl-process och verifierar bland annat:

• status med specifik månad och med period: null,
• Doctor-rendering och exitkoder,
• merchant- och kuvertlistor,
• TAB-komplettering,
• köp genom preview/apply,
• merchant- och kuvertskapande samt kuvertuppdatering,
• återanvändning av exakt request,
• revisions-, digest- och dubblettskydd,
• att direkt arbetsyteåtkomst och godtyckliga subprocesser blockeras.