Référence CLI Beancount

Utilisez cette référence pour consulter les commandes bea et leur comportement. Pour votre premier grand livre, suivez le guide de démarrage rapide CLI. Pour les fichiers bancaires, utilisez le guide d'importation.

Commandes en un coup d'œil​

Options globales et chemins​

Les options globales se placent avant la commande :

bea --file ~/my-books/main.bean check
bea --json list transaction --limit 100

init crée sa propre cible de répertoire/fichier et ignore BEA_FILE. Il accepte l'option globale --file à la place de son argument de répertoire. format utilise sa propre cible positionnelle, par défaut le répertoire de travail. L'option globale --file ne choisit pas la cible de formatage.

Créer un grand livre​

bea init [DIRECTORY] utilise par défaut le répertoire courant. Un répertoire crée main.bean ; un chemin .bean ou .beancount nomme directement le nouveau fichier.

Le modèle ouvre Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees et Equity:OpeningBalances.

Les soldes d'ouverture sont compensés par Equity:OpeningBalances. La dette est négative. La devise est convertie en majuscules. Les symboles personnalisés sont autorisés ; un symbole qui n'est pas composé de trois lettres majuscules déclenche un avertissement de faute de frappe. Ce n'est pas un contrôle du registre des devises ISO.

Les fichiers existants ne sont jamais écrasés. Les nouveaux fichiers utilisent des permissions réservées au propriétaire, mode 0600 sur POSIX. Les écritures ultérieures d'ajout, d'importation et de formatage préservent les permissions et respectent les destinations en lecture seule.

Ajouter des transactions​

bea add transaction -n "Groceries" --payee "Corner Market" \
  -p "Expenses:Groceries 30" -p "Assets:Checking" \
  --flag '!' --tag household --link receipt-42 --meta 'receipt:IMG_42.jpg'

Une écriture peut omettre son montant. Les écritures numérotées peuvent omettre la devise lorsque le compte a une devise autorisée ou que le grand livre a une devise de fonctionnement compatible unique. Sinon, fournissez le symbole.

La syntaxe native des écritures prend en charge l'arithmétique telle que 84/2 EUR, les coûts tels que {100 USD}, les coûts totaux {{1000 USD}} et les prix @ ou @@. Utilisez des montants décimaux comme 1000, pas une notation en exposant comme 1e3.

Un change de devise nécessite son taux de transaction réel. Par exemple, enregistrez 100 EUR @ 1.08 USD sur un compte ouvert en EUR et -108 USD sur le compte courant. Un achat d'investissement peut enregistrer 2 AAPL {100 USD} sur un compte ouvert en AAPL et -200 USD sur le compte courant. Ajoutez des cotations price datées lorsque les rapports nécessitent une évaluation au prix du marché.

Les métadonnées acceptent les chaînes nues comme --meta 'receipt:IMG_42.jpg'. Les nombres natifs, les booléens, les dates et les montants conservent leurs types. Exemples : --meta 'reviewed:TRUE', --meta 'received:2026-08-03' et --meta 'fee:2.50 USD'. Les guillemets internes forcent une chaîne : --meta 'code:"1234"'. Les clés doivent être distinctes ; filename et lineno sont réservées.

Les ajouts uniques, les ajouts en masse et les importations remplacent les sauts de ligne dans les bénéficiaires, les narrations et les métadonnées de chaîne par des espaces. Les guillemets et les barres obliques inverses conservent leur contenu.

Ajouter d'autres directives​

Toutes ces commandes nécessitent --date YYYY-MM-DD. Elles acceptent également --into FILE et --allow-errors.

Les noms de comptes ont une racine en majuscules et des segments séparés par deux-points. Chaque sous-compte commence par une lettre majuscule ou un chiffre. Beancount prend en charge les lettres Unicode et les noms de racines configurés.

Un solde vérifie le compte au début de sa date. La syntaxe de tolérance est prise en charge, comme --amount "1538 ~ 1 EUR". La tolérance doit être non négative.

Utilisez add balance --pad-from Equity:OpeningBalances pour écrire un coussin (pad) et son assertion de solde ensemble. Le coussin utilise par défaut le jour précédent ; --pad-date peut sélectionner un autre jour antérieur. Les deux comptes doivent être actifs. Un coussin autonome a besoin d'un solde ultérieur pour être consommé. --allow-errors peut préparer cet état intermédiaire mais ne peut pas contourner un compte de coussin invalide.

add price ignore un doublon exact de date/produit/prix entre la racine et ses fichiers inclus. Il quitte avec le code 0 et identifie l'emplacement existant. Des dates ou des prix différents sont de nouveaux ajouts.

Les chemins de documents se résolvent à côté du fichier contenant la directive. Avec --into years/2026.bean, --filename receipt.pdf signifie years/receipt.pdf, pas un fichier à côté du répertoire de travail de votre shell.

Les types de valeurs personnalisées sont text, number, amount, account, bool et date. Par exemple, un budget peut utiliser --value "text:travel" --value "amount:500 USD".

Entrée JSON en masse​

bea add transactions --from transactions.json accepte un tableau JSON :

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

Chaque transaction nécessite date et postings. Les champs facultatifs sont flag, payee, narration, tags, links et meta.

Une écriture utilise amount ou units, comme {"number":"45.00","currency":"USD"}. Omettez les deux pour l'écriture d'équilibrage. Les champs d'écriture incluent également cost, price, flag et meta. Les coûts contiennent number et currency, avec date et label facultatifs. Les prix contiennent number et currency.

Utilisez des chaînes pour les nombres décimaux. Les métadonnées utilisent des chaînes et des booléens ordinaires, ou des valeurs étiquetées comme {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} et {"kind":"amount","number":"2.50","currency":"USD"}. L'emplacement source facultatif de la transaction n'est jamais écrit comme métadonnée.

Le défaut est un lot atomique : toute ligne rejetée laisse le grand livre inchangé et quitte avec le code 1. --partial écrit un sous-ensemble valide et quitte toujours avec le code 1 si des lignes sont rejetées. Les erreurs JSON décrivent le résultat dans error.result ; les index de lignes y sont basés sur zéro. Les numéros de lignes humains sont basés sur un.

L'ajout en masse accepte --into et --allow-errors. Il ne déduplique pas. Utilisez bea import pour l'examen des exportations bancaires.

Grands livres divisés et sécurité d'écriture​

Gardez --file pointé sur la racine. Ajoutez --into pour sélectionner un fichier inclus existant :

bea --file ~/my-books/main.bean add transaction --into 2026.bean \
  --date 2026-08-02 -n "Groceries" \
  -p "Expenses:Groceries 30" -p "Assets:Checking"

La destination est relative au répertoire racine. Elle doit déjà être incluse ; nommer un fichier non lié est refusé. Les commandes d'ajout, les importations et les écritures IA interactives prennent en charge cette séparation.

Les écritures valident le grand livre candidat complet, y compris les plugins et la réservation des lots de coûts. Une modification concurrente de la racine ou de son graphique d'inclusion quitte avec le code 4. Une destination en lecture seule quitte avec le code 3. Les ajouts réussis utilisent le même alignement que bea format, ce qui peut réaligner les colonnes existantes dans cette destination.

Lister les directives​

bea list TYPE prend en charge les onze types : transaction, open, close, balance, pad, note, event, price, commodity, document et custom.

Les autres types de directives conservent l'ordre chronologique. Une table de transactions filtrée par compte étiquette sa colonne de montants MATCHING POSTING AMOUNTS. Les détails et le JSON incluent toujours toutes les écritures de chaque transaction sélectionnée. Les détails affichent les entrées chargées, y compris les montants déduits ; ce ne sont pas des extraits bruts de la source.

Vérifier, formater et interroger​

bea check valide la racine et les fichiers inclus. Il quitte avec le code 1 pour les erreurs du grand livre et n'a pas d'option --allow-errors. Les requêtes, les listes et les rapports rejettent également les erreurs de chargement sauf si vous passez explicitement leur option --allow-errors.

Le formatage prend un fichier .bean/.beancount ou un répertoire. Un répertoire est recherché de manière récursive.

Chaque mode rapporte les erreurs de syntaxe par fichier et ligne, ignore ces fichiers et quitte avec le code 1. Un exécution récursive normale peut toujours formater les fichiers valides. Le JSON rapporte scanned, formatted, skipped, dry_run et check, sous error.result en cas d'échec.

bea query "BQL" exécute une requête Beancount. Omettre le BQL ouvre un shell interactif ; exit ou quit le ferme. Un argument de requête est requis en mode non interactif. La table par défaut de BQL a une ligne par écriture. Les tables de requête conservent la précision. Les résultats vides affichent (no rows) sur stderr ; le JSON renvoie un data.rows vide et les métadonnées de colonnes dans data.columns.

Rapports financiers​

Tous les rapports acceptent --conversion / -x, --time / -t, --account / -a et --allow-errors. Tous sauf le bilan de vérification acceptent également --interval / -i : monthly par défaut, ou quarterly, yearly, weekly ou daily.

Les filtres de temps incluent une année, un mois, une date, un trimestre, une semaine ou une plage, comme 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 ou "2026-01 - 2026-08". Les périodes relatives incluent year, quarter, month, week, day et des décalages comme month-1. Les filtres de compte conservent chaque écriture d'une transaction correspondante.

La conversion utilise par défaut la devise de fonctionnement unique du grand livre. Sinon, elle utilise par défaut units, gardant les produits séparés. at_cost utilise les coûts d'acquisition. at_value utilise les valeurs de marché avec un repli sur le coût.

Une conversion de devise explicite nécessite des prix à la date ou avant chaque date d'évaluation, y compris les dates d'intervalle. Une erreur de prix manquant nomme l'écart réel, comme No EUR → USD price on or before 2026-01-31. Une cotation ultérieure ne peut pas combler un écart antérieur. Ajoutez un prix historiquement approprié, utilisez --conversion units ou choisissez --allow-errors pour inspecter les valeurs partielles.

Les rapports partiels conservent les devises sources et marquent les totaux combinés comme indisponibles. Le JSON inclut valuation: "partial", missing_prices et missing_price_dates. Les totaux de bénéfice net/valeur nette affectés sont null dans la devise demandée.

Les revenus, les passifs et les fonds propres utilisent normalement les signes Beancount négatifs. Le bénéfice net est -(income + expenses), positif pour un gain. La même convention s'applique aux lignes de périodes du compte de résultat. Le rapprochement du bilan est dérivé pour le rapport ; il n'écrit aucune directive. equity_reconciled identifie si un rapprochement complet est disponible.

Le JSON du rapport identifie également la période, la date de fin exclusive, la date d'as-of, la conversion, le filtre de compte et l'état de validation du grand livre. Vérifiez ces champs avant de comparer les totaux.

Assistance IA facultative​

bea ask nécessite à la fois l'extension ask et des identifiants Beancount.io via bea cloud login ou BEA_TOKEN. L'installation Homebrew par défaut omet les dépendances IA. Les utilisateurs Homebrew peuvent exécuter :

bea cloud login
uvx --from 'beancount-io[ask]' bea ask "What did I spend last month?" --print

Pour une installation uv, installez beancount-io[ask] et exécutez bea ask directement. --print / -p répond une fois et quitte. Sinon, une session terminale est interactive, et une question facultative pré-remplit son entrée. L'utilisation non interactive nécessite une question. Le mode JSON n'est pas pris en charge.

Les requêtes s'exécutent localement. Les questions, le contexte de compétences et les résultats d'outils vont au service IA hébergé Beancount.io. Les écritures interactives sont prévisualisées, confirmées, validées et écrites atomiquement. Elles acceptent --into. L'option globale --yes n'accorde pas la permission d'écriture IA. Le mode à réponse unique n'applique pas les écritures proposées.

Ask lit NAME/SKILL.md depuis .agents/skills/ dans le répertoire de travail et depuis skills/ dans le répertoire de configuration utilisateur. Les définitions de projet gagnent par nom. Chaque fichier nécessite des champs YAML name et description. Les instructions complètes se chargent à la demande.

Grands livres hébergés​

La création accepte également --clone et --dir. L'accès Git et SSH est requis pour cloner. Si le clonage échoue après la création, le grand livre hébergé existe toujours. Les commandes locales ne téléchargent pas votre grand livre automatiquement. Il n'y a pas d'option globale --ledger.

JSON et codes de sortie​

L'option globale --json place les résultats réussis sur stdout :

{
  "bea": "0.1.0",
  "target": { "file": "/home/alice/my-books/main.bean" },
  "data": [],
  "truncated": false,
  "limit": 50
}

bea est la version installée ; data dépend de la commande. Les cibles identifient un fichier, un répertoire, un serveur ou aucune cible. Les écritures incluses identifient également into. Les montants décimaux et les dates utilisent des chaînes. Les listes limitées incluent limit et truncated.

Les échecs écrivent {"error":{"category":"validation","message":"…","exit_code":1}} sur stderr. L'erreur peut également inclure details, result, un request_id backend et une traceback avec --debug.

Vérifiez error.result avant de réessayer une mutation. Un lot partiel peut écrire des lignes acceptées, un formatage récursif peut modifier des fichiers valides, et créer-et-cloner peut créer un grand livre hébergé avant de quitter avec un code non nul.

Les invites CLI sont désactivées par --no-input, le mode JSON, stdin non terminal ou CI vrai. La suppression cloud nécessite toujours un --yes explicite. Les importations nécessitent une décision de doublon explicite lorsque des correspondances doivent être examinées.

Exceptions de sortie : Ask rejette le JSON ; la connexion cloud nécessite une interaction ; la déconnexion et le clonage cloud réussis ne renvoient aucun objet de succès JSON. L'aide, la version et la complétion conservent une sortie texte. upgrade peut diffuser la sortie de son gestionnaire de paquets sur stderr, y compris en mode JSON.

Paramètres, mises à jour et état stocké​

Les valeurs vraies sont 1, true, yes et on, en ignorant la casse et les espaces environnants. L'état de configuration inclut les identifiants, l'historique des invites Ask, les compétences utilisateur, les chemins d'importateur mémorisés et les caches de vérification de mises à jour. Les verrous d'écriture vivent sous locks/ du répertoire cache, en dehors de votre répertoire de grand livre.

bea upgrade --check rapporte les versions et la méthode d'installation sans mettre à niveau. bea upgrade invoque brew upgrade bea, uv tool upgrade beancount-io ou pipx upgrade beancount-io. Les installations modifiables reçoivent des conseils de mise à jour manuelle. Les vérifications passives s'exécutent au plus une fois par jour dans les copies installées interactives ; upgrade --check explicite s'exécute toujours lorsque le notificateur passif est désactivé.

Désinstallez avec le gestionnaire correspondant : brew uninstall bea, uv tool uninstall beancount-io ou pipx uninstall beancount-io. Vos fichiers de grand livre et votre configuration utilisateur restent.

Corrections courantes​

Utilisez bea COMMAND --help pour inspecter votre version installée. La référence du référentiel source contient des exemples supplémentaires et les définitions exactes du modèle de directive.