Démarrage rapide avec l'interface CLI Beancount

Créez un journal local et enregistrez votre premier achat avec bea, l'outil en ligne de commande de Beancount.io. La tenue de livres locale ne nécessite pas de compte Beancount.io.

Cette procédure part avec 1 000 USD sur le compte chèque. Après un achat de café de 12,50 USD, vous vérifierez un solde de 987,50 USD.

1. Installer la commande​

Avec Homebrew sur macOS ou Linux :

brew install bex-co/tap/bea
bea --version

Si vous n'utilisez pas Homebrew, installez uv et utilisez uv tool install beancount-io. Le paquet Python nécessite Python 3.12 ou plus récent.

2. Créer votre journal​

Choisissez un nouveau répertoire. Cet exemple crée main.bean dans ~/my-books :

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

Le modèle ouvre des comptes courants de chèques, d'épargne, d'espèces, de cartes de crédit, de revenus et de dépenses. Le solde d'ouverture est compensé par Equity:OpeningBalances.

Pour vos propres livres, choisissez la date la plus ancienne que vous prévoyez d'enregistrer. Tous les comptes du modèle s'ouvrent à cette date. Le solde d'ouverture doit décrire le compte à cette date. La dette de carte de crédit utilise un montant négatif.

init ne remplace jamais un journal existant. Les nouveaux fichiers sont privés sur les systèmes POSIX : seul le propriétaire peut les lire et les écrire. Pour partager avec votre groupe d'utilisateurs local, modifiez explicitement les permissions avec chmod 640 main.bean.

Pour une configuration guidée, exécutez plutôt bea init ~/my-books dans un terminal. L'assistant demande votre devise, la date de début de l'historique et le solde du compte chèque.

3. Enregistrer un achat​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

La dépense utilise la devise USD du compte. Beancount remplit automatiquement l'autre écriture avec -12.50 USD. Vous pouvez omettre --date pour les achats effectués aujourd'hui.

Chaque ajout est vérifié par rapport au journal complet avant que le fichier ne soit remplacé. Un compte inconnu ou une transaction non équilibrée produit une erreur avec des conseils.

4. Vérifier le résultat​

bea check
bea list transaction --limit 10
bea report balance-sheet

La liste des transactions montre les entrées les plus récentes en premier, avec leurs montants d'écritures. Le bilan montre 987,50 USD sur le compte chèque.

Pour vérifier ce montant directement :

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Les tableaux de requêtes préservent la précision du résultat. Pour une sortie structurée, placez l'option globale --json avant la commande :

bea --json list transaction --limit 10

5. Gardez vos livres en bon état​

Exécutez bea check après avoir modifié le fichier à la main. Exécutez bea format main.bean pour aligner ses colonnes. Utilisez bea format main.bean --check lorsqu'un script doit échouer si une mise en forme est nécessaire.

Pour travailler depuis un autre répertoire, sélectionnez le fichier racine explicitement :

bea --file ~/my-books/main.bean check

La racine est sélectionnée par --file, puis BEA_FILE, puis main.bean dans le répertoire de travail. Les options globales vont avant la commande. La mise en forme prend son propre argument de fichier ou de répertoire.

Continuez avec vos propres enregistrements​

• Importer un export bancaire avec un aperçu et une revue des doublons.
• Consulter les commandes et les options pour les comptes, les soldes, les investissements, les rapports et l'automatisation.
• Organiser un journal sur plusieurs fichiers. Utilisez --into pour écrire un fichier inclus tout en validant par rapport à la racine.
• Utiliser l'interface navigateur si vous préférez les formulaires aux commandes terminal.

Vérifiez les mises à jour avec bea upgrade --check. Exécutez bea upgrade pour invoquer le gestionnaire de paquets qui a installé votre copie. Utilisez bea --help ou bea add transaction --help pour inspecter les options disponibles dans votre version installée.