Référence CLI Beancount

Utilisez cette référence pour consulter les commandes bea et leur comportement. Pour votre premier registre, suivez le démarrage rapide de la CLI. Pour clôturer un mois complet de bout en bout, parcourez Votre premier mois avec bea. Pour les fichiers bancaires, utilisez le tutoriel d'import.

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 au lieu de son argument de répertoire. format utilise sa propre cible positionnelle. Fournissez un nom de fichier ou un répertoire. 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, Expenses:Uncategorized et Equity:OpeningBalances.

Les soldes d'ouverture sont compensés contre Equity:OpeningBalances. Une dette est négative. La saisie de 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. Il ne s'agit pas d'une vérification du registre ISO des devises.

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 et d'import préservent les permissions et respectent les destinations en lecture seule. Le formatage sur place utilise le formateur natif et signale ses propres erreurs de système de fichiers.

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 lorsqu'un compte a une seule devise autorisée ou que le registre a une seule devise de fonctionnement compatible. Sinon, indiquez 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 la notation exponentielle comme 1e3.

Un échange de devises nécessite son taux de transaction réel. Par exemple, inscrivez 100 EUR @ 1.08 USD sur un compte ouvert en EUR et -108 USD sur le compte courant. Un achat de placement peut inscrire 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 valorisation de marché.

Les métadonnées acceptent des chaînes nues telles que --meta 'receipt:IMG_42.jpg'. Les nombres, booléens, dates et montants natifs conservent leurs types. Les exemples incluent --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és.

Les ajouts simples, les ajouts en masse et les imports remplacent les sauts de ligne dans les bénéficiaires, les libellés et les métadonnées de type 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 aussi --into FILE et --allow-errors.

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

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

Utilisez add balance --pad-from Equity:OpeningBalances pour écrire un pad et son assertion de solde ensemble. Le pad est daté par défaut de la veille ; --pad-date peut sélectionner un autre jour antérieur. Les deux comptes doivent être actifs. Un pad autonome nécessite un solde ultérieur pour le consommer. --allow-errors peut préparer cet état intermédiaire mais ne peut pas contourner un compte de pad invalide.

add price ignore un doublon exact date/titre/prix dans la racine et ses inclusions. Il termine 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, et non un fichier à côté du répertoire de travail de votre shell.

Les types de valeur personnalisés 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 soit amount, soit units, par exemple {"number":"45.00","currency":"USD"}. Omettez les deux pour l'écriture d'équilibrage. Les champs d'écriture incluent aussi 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 décimales. Les métadonnées utilisent des chaînes et des booléens ordinaires, ou des valeurs étiquetées telles que {"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.

La valeur par défaut est un lot atomique : toute ligne rejetée laisse le registre inchangé et termine avec le code 1. --partial écrit un sous-ensemble valide et termine quand même avec le code 1 si des lignes sont rejetées. Les erreurs JSON décrivent le résultat dans error.result ; les index de ligne y sont basés sur zéro. Les numéros de ligne humains sont basés sur un.

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

Grand livres divisés et sécurité d’écriture​

Gardez --file pointé vers 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 imports et les écritures IA interactives prennent en charge cette séparation.

Les écritures valident le registre candidat complet, y compris les plugins et la comptabilisation des lots de coûts. Une modification concurrente de la racine ou de son graphe d'inclusion termine avec le code 4. Une destination en lecture seule termine avec le code 3. Les ajouts réussis alignent uniquement les nouvelles lignes. Les octets existants restent inchangés. Utilisez bea format -i PATH lorsque vous souhaitez réaligner le fichier entier.

Liste des 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. Un tableau de transactions filtré 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 inclusions. Il termine silencieusement avec le code 0 en cas de succès et 1 en cas d'erreurs dans le registre. L'option globale --json renvoie l'enveloppe de validation. Il n'y a pas d'option --allow-errors pour check.

Les requêtes, les listes et les rapports avertissent et renvoient des résultats partiels dans un terminal interactif. L'option globale --strict, --json, --no-input, la variable CI vraie ou l'entrée standard non terminal rendent les lectures strictes. Leur option --allow-errors autorise explicitement les résultats partiels.

Le formatage accepte des fichiers ou recherche récursivement dans un répertoire. Dans le paquet publié 0.2.0, un chemin est requis malgré la valeur par défaut stdin indiquée dans l'aide. L'option globale --file ne choisit pas la cible de formatage.

Le formatage aligne le texte ; il ne valide pas la syntaxe du registre ni la comptabilité. Exécutez bea check séparément. Avec l'option globale --json, sélectionnez -i, -o FILE, --check ou --dry-run pour que stdout puisse transporter l'enveloppe. Ne redirigez pas stdout vers le fichier d'entrée : utilisez -i pour le réécrire.

bea query "BQL" exécute une requête Beancount. Omettre BQL lit les requêtes depuis stdin ou ouvre le shell lorsque stdin est un terminal. Utilisez .exit, exit ou quit pour fermer le shell. Le tableau par défaut de BQL a une ligne par écriture. Les tableaux de requête conservent la précision.

Sélectionnez le registre avant la commande, par exemple bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". L'option globale --json utilise l'enveloppe du produit avec data.rows et data.columns ; elle est distincte du rendu CSV. Dans la version publiée 0.2.0, utilisez la redirection du shell pour enregistrer le JSON, par exemple bea --json query "SELECT account, sum(position) GROUP BY account" > result.json : les options -o et -m de query ne s'appliquent pas au JSON dans cette version.

Outils natifs et fonctionnalités optionnelles​

bea doctor context main.bean 42 affiche le contexte de la transaction à la ligne 42. bea doctor --help liste les autres commandes de diagnostic. bea example -o example.bean crée un historique d'exemple. bea treeify accounts.txt affiche des noms hiérarchiques à partir d'un fichier texte ; omettez le fichier pour lire stdin. Ces commandes transmettent les arguments natifs. Les exemples ci-dessus nomment explicitement ces arguments.

Activez les outils facultatifs une fois avec bea engine enable beanprice pour la récupération des cotations ou bea engine enable beangulp pour les workflows d'import. L'activation nécessite un accès réseau ; Beangulp nécessite aussi la bibliothèque système libmagic. Utilisez bea engine status pour inspecter la disponibilité. bea price --help et bea ingest --help décrivent leurs interfaces. bea import --csv et bea add price n'ont besoin d'aucune de ces fonctionnalités facultatives.

Inclusions de prix gérées​

Live Prices est un workflow distinct d'inclusion gérée. Les registres hébergés résolvent les URL de prix prises en charge ; les versions compatibles de bea prennent également en charge les inclusions gérées et les exports de prix locaux. Consultez le guide des prix gérés propre à chaque version si votre version installée ne reconnaît pas ces commandes.

La CLI résout les URL gérées figurant sur la liste blanche sans envoyer d'identifiants et refuse les redirections. Un flux qui redirige vers une connexion hébergée est donc indisponible pour une récupération locale fraîche ; se connecter au site web n'authentifie pas la requête de prix de la CLI. Inspectez price status pour les erreurs de source. Utilisez les données en cache, un flux pris en charge joignable ou des prix datés locaux selon le cas.

price export écrit les fichiers de flux sous prices/ et réécrit les inclusions vers des chemins relatifs locaux. Beancount, Fava et Beanquery en amont peuvent charger cette copie exportée. Une source indisponible refuse l'export sauf si --allow-errors est utilisé, ce qui peut laisser son marqueur de source sans prix.

Votre propre prix daté remplace un prix géré pour la même date et la même paire. Les entrées de flux sont en lecture seule. Les actualisations échouées conservent une révision précédemment validée, qui peut être obsolète. Les autres arguments de bea price sont toujours transmis à Beanprice ; si un fichier de tâche de cotation s'appelle status, passez ./status pour le distinguer de la sous-commande.

Homebrew installe à la fois la CLI et son moteur géré. Avec PyPI, la première commande adossée au moteur télécharge les dépendances épinglées ; gardez uv dans le PATH et autorisez l'accès réseau pour cette première exécution. Les commandes locales ultérieures réutilisent le moteur hors ligne. Les clients installent uniquement beancount-io, sans paquet Beancount séparé ni scripts de console natifs à gérer.

Rapports financiers​

Tous les rapports acceptent --conversion / -x, --time / -t, --account / -a et --allow-errors. Tous sauf la balance générale acceptent aussi --interval / -i : monthly par défaut, ou quarterly, yearly, weekly ou daily.

bea balance [ACCOUNT...] affiche les sous-arbres de soldes des comptes correspondant à des sous-chaînes insensibles à la casse, ou le registre entier si vous n'en nommez aucun. Il accepte --conversion / -x, --time / -t et --allow-errors, et ne prend aucune option d'intervalle ni de compte.

Les filtres temporels incluent une année, un mois, une date, un trimestre, une semaine ou une plage, tels que 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 tels que month-1. Les filtres de compte conservent chaque écriture d'une transaction correspondante.

La conversion utilise par défaut la seule devise de fonctionnement du registre. Sinon, elle utilise par défaut units, en gardant les titres 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 de chaque date de valorisation ou avant, y compris les dates d'intervalle. Une erreur de prix manquant nomme l'écart réel, par exemple 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 des 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 concernés sont null dans la devise demandée.

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

Le JSON des rapports identifie aussi la période, la date de fin exclusive, la date d'arrêté, la conversion, le filtre de compte et l'état de validation du registre. Vérifiez ces champs avant de comparer des totaux.

Assistance IA optionnelle​

bea ask nécessite à la fois l'extra ask et les identifiants Beancount.io provenant de bea cloud login ou de BEA_TOKEN. L'installation Homebrew par défaut omet les dépendances d'IA. Les utilisateurs de 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 se termine. Sinon, une session terminal 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étence 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 à l'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 de l'utilisateur. Les définitions de projet l'emportent par nom. Chaque fichier nécessite les champs YAML name et description. Les instructions complètes se chargent à la demande. Pour la disposition des fichiers et un exemple concret, voir Étendre bea ask avec des compétences.

Registres hébergés​

Avec l'option globale --json, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create et bea cloud ledger delete émettent l'enveloppe standard. La connexion nécessite une interaction ; une déconnexion et un clone réussis ne renvoient pas d'objet de succès JSON.

La création accepte aussi --clone et --dir. Git et SSH sont requis pour cloner. Si le clone échoue après la création, le registre hébergé existe toujours. Les commandes locales ne téléversent pas automatiquement votre registre. 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.2.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 aussi 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 aussi inclure details, result, un request_id de backend et un traceback avec --debug.

Vérifiez error.result avant de réessayer une mutation. Un lot partiel peut écrire les lignes acceptées, le formatage récursif peut modifier des fichiers valides, et create-and-clone peut créer un registre hébergé avant de terminer avec un code non nul. Pour un script qui lit cette enveloppe avec jq et bifurque sur ces codes, voir Automatiser la comptabilité avec bea.

Les invites de la CLI sont désactivées par --no-input, le mode JSON, une entrée standard non terminal ou la variable CI vraie. La suppression dans le cloud nécessite toujours un --yes explicite. Les imports nécessitent une décision explicite sur les doublons lorsque des correspondances doivent être examinées.

Exceptions de sortie : doctor, example, treeify, les invocations price transmises à Beanprice et ingest conservent la sortie native et le statut de sortie, même avec l'option globale --json ; l'enveloppe et les catégories de sortie ci-dessus ne décrivent pas ces résultats transmis. Ask rejette JSON ; la connexion cloud nécessite une interaction ; une déconnexion et un clone cloud réussis ne renvoient pas d'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, sans tenir compte de la casse et des espaces environnants. L'état de configuration inclut les identifiants, l'historique des invites Ask, les compétences utilisateur, les chemins d'import mémorisés et les caches de vérification des mises à jour. Les verrous d'écriture se trouvent sous locks/ dans le répertoire de cache, en dehors de votre répertoire de registre.

bea upgrade --check signale 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 manuels. 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 registre et votre configuration utilisateur restent.

Correctifs courants​

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