본문으로 건너뛰기
Beancount.io Logo
bea로 부기 자동화하기

bea로 부기 자동화하기

bea로 Beancount 장부를 스크립팅하세요: 원장을 명시적으로 지정하고, jq로 JSON 봉투를 파싱하고, 종료 코드로 분기하고, 무인 실행하고, 야간 점검을 예약하세요.

스크립트는 네 가지 결정으로 bea를 구동합니다: 읽을 원장, 기계 판독 가능한 출력을 위한 --json, 필요한 값을 위한 jq, 분기할 종료 코드입니다. 이 가이드는 이 네 가지 결정을 처음부터 끝까지 설명한 다음 예약까지 다룹니다.

작업을 실행하는 머신에 bea가 있고 접근 가능한 원장이 필요합니다. 새 장부를 시작하는 경우 먼저 CLI 빠른 시작을 따르세요. 플래그, 봉투 키, 종료 코드에 대한 모든 사실은 Beancount CLI 참조에서 확인할 수 있으며, 여기서 반복하지 않습니다.

원장을 명시적으로 선택하기​

파일을 지정하세요. 로컬 명령은 --file, 그다음 $BEA_FILE, 그다음 작업 디렉터리의 ./main.bean 순서로 대상을 결정합니다. 예약된 작업은 예상한 위치에서 실행되는 경우가 드뭅니다.

bea --file ~/books/main.bean check
BEA_FILE=~/books/main.bean bea check
cd ~/books && bea check

전역 옵션은 bea --file main.bean check처럼 명령 앞에 옵니다. 해석된 파일이 존재하지 않으면 명령은 세 가지 소스를 모두 명명하며 종료 코드 2로 종료됩니다. 따라서 cron 항목의 오타는 잘못된 장부를 검증하는 대신 큰 소리로 실패합니다. --ledger 플래그를 통한 호스팅 대상 지정은 아직 존재하지 않습니다. bea는 로컬 파일을 암시적으로 업로드하지 않습니다.

JSON 봉투 읽기​

전역 --json을 추가하면 지원되는 모든 명령이 동일한 봉투로 응답합니다: bea, target, data, truncated, 그리고 제한된 목록의 limit. 금액은 소수 문자열이고 날짜는 ISO YYYY-MM-DD이므로 값은 파이프라인에 부동 소수점이 들어가지 않고도 비교하기에 안전합니다. 봉투의 키는 JSON 및 종료 코드 참조에 표로 정리되어 있습니다.

bea --json --file main.bean report income-statement | jq .data.net_profit
bea --json --file main.bean list transaction --limit 2 | jq '.data[0].postings[0].units'
bea --json --file main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee \
  --account Assets:Checking --apply --duplicates skip | jq '.data | {written, ready, duplicates}'

세 명령 — report, list, import — 은 결과 형태를 유지하므로 이에 맞게 작성된 jq 경로는 유효하게 유지됩니다. bea --json check와 bea --json query도 오늘날 봉투를 출력하지만, 이들은 네이티브 Beancount 실행 파일에 전달되는 명령이므로 스크립트는 출력 형태보다 check의 종료 상태를 기준으로 해야 합니다. 중복 정책을 의도적으로 선택하세요: import 연습에서 설명하듯이 import에 결정이 필요할 때 여전히 --duplicates가 필요합니다.

올바른 종료 코드에서 중지하기​

상태에 따라 분기하고, 쓰기 작업을 재시도하기 전에 오류 객체를 읽으세요. --json 모드에서 실패는 stdout에 아무것도 쓰지 않고 stderr에 정확히 하나의 객체를 쓰며, 해당 객체의 error.category는 클래스를 명명합니다: validation (1), usage (2), auth (3), conflict (4).

#!/usr/bin/env bash
set -euo pipefail
 
out=$(mktemp)
err=$(mktemp)
status=0
 
bea --json --file main.bean report income-statement >"$out" 2>"$err" || status=$?
 
case "$status" in
  0) jq -r '.data.net_profit | to_entries[] | "net profit: \(.value) \(.key)"' "$out" ;;
  4) echo "conflict — inspect the ledger before retrying" >&2
     jq -r '.error.message' "$err" >&2
     exit 4 ;;
  *) jq -r '.error | "\(.category) (exit \(.exit_code)): \(.message)"' "$err" >&2
     exit "$status" ;;
esac

종료 4는 스크립트가 절대 맹목적으로 재시도해서는 안 되는 코드입니다. 결과가 충돌이거나 알 수 없음을 의미하기 때문입니다. 예를 들어 쓰기 도중 외부 편집이 발생하거나 이미 존재하는 init 대상이 있는 경우입니다. 원장을 검사한 다음 새로 읽은 상태에서 재시도하세요. 종료 1은 검증 실패 및 기타 모든 런타임 오류를 포함합니다. error.details는 개별 원장 오류를 전달하고, error.result는 부분 쓰기가 실제로 수행한 작업을 전달합니다. 0이 아닌 종료는 아무것도 변경되지 않았음을 보장하지 않습니다.

터미널 없이 실행하기​

bea는 스스로 프롬프트를 중지합니다. stdin이 터미널이 아닐 때, --json이 설정되었을 때, CI가 truthy일 때 — 1, true, yes 또는 on — --no-input이 암시됩니다. 이 모드에서는 확인 누락이 영원히 기다리는 대신 종료 2로 실패합니다.

CI=true BEA_NO_UPDATE_NOTIFIER=1 bea --json --file main.bean report balance-sheet
bea --json --file main.bean list transaction --limit 100 --sort oldest

읽기는 터미널에서 관대하고 다른 모든 곳에서 엄격합니다. 원장에 로더 오류가 있을 때 query, list, report는 --json 아래, 파이프된 stdout 아래, truthy한 CI 아래, 또는 --strict와 함께 종료 1로 종료됩니다. 대신 부분 답변을 수용하려면 명령 자체의 --allow-errors를 전달하세요. 이는 JSON에서 ledger_valid: false를 설정하고 ledger_errors를 채웁니다. --strict는 그 반대입니다. 터미널에서도 부분 답변을 거부하며, 사람이 같은 스크립트를 직접 실행할 때 원하는 동작입니다. bea check에는 --allow-errors가 없습니다 — 오류 보고가 전체 작업이므로 — 오류를 찾으면 항상 종료 1로 종료됩니다. BEA_NO_UPDATE_NOTIFIER=1을 설정하여 수동적 업데이트 알림을 음소거하세요. truthy한 CI는 이미 그렇게 합니다.

점검 예약하기​

매일 밤 검증을 실행하고 종료 코드가 알림 역할을 하게 하세요. 아래 두 블록은 모두 템플릿입니다 — 경로, 일정, 실행기는 여러분의 것입니다.

# crontab -e — 07:15 daily; cron mails you only when bea exits nonzero
15 7 * * * BEA_NO_UPDATE_NOTIFIER=1 /opt/homebrew/bin/bea --file /home/alice/books/main.bean check
name: ledger
on:
  schedule:
    - cron: "15 7 * * *"
  push:
jobs:
  check:
    runs-on: ubuntu-latest
    env:
      BEA_NO_UPDATE_NOTIFIER: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install beancount-io==0.1.0
      - run: bea --file main.bean check
      - run: bea --json --file main.bean report balance-sheet > balance-sheet.json

작업이 재현 가능해야 할 때 버전을 고정하고, 릴리스를 추적하고 싶다면 고정을 해제하세요. GitHub Actions에서 CI는 이미 truthy하므로 아무것도 설정하기 전에 프롬프트가 꺼지고 업데이트 알림이 조용해집니다. 여기에 의도적으로 형식 지정 단계가 없습니다. 예약된 작업은 할 필요가 없는 파일을 다시 쓰지 않아야 하므로, 아무것도 건드리지 않고 파일에 형식 지정이 필요할 때 종료 1로 종료되는 bea format --check를 pre-commit 훅에서 사용하세요.

작업에서 호스팅 자격 증명 사용하기​

CI 제공자의 비밀 저장소에서 BEA_TOKEN을 설정하고 브라우저 로그인을 완전히 건너뛰세요. 토큰은 환경에서 읽히고 디스크에 절대 기록되지 않으므로 실행기의 홈 디렉터리에 다음 작업이 찾을 수 있는 것이 아무것도 남지 않습니다.

export BEA_TOKEN="$YOUR_CI_SECRET"
bea --json cloud status

종료 0은 자격 증명이 해석되었고 봉투가 속한 계정을 명명함을 의미합니다. error.category가 auth인 종료 3은 그렇지 않음을 의미하며, 메시지는 설정되지 않은 자격 증명과 거부된 자격 증명을 구분합니다. bea cloud logout은 이렇게 제공된 토큰에 대해 아무것도 하지 않습니다 — 다른 작업이 공유할 수 있으므로 취소하지도 해제하지도 않습니다 — 따라서 유출된 토큰은 대시보드에서 취소하세요. 로컬 명령에는 자격 증명이 전혀 필요 없습니다. 호스팅 서비스에 도달하는 것은 bea cloud와 bea ask뿐입니다. 전체 변수 목록은 설정 참조에 있습니다.

모든 것이 JSON으로 응답하는 것은 아닙니다. bea ask는 JSON 모드를 완전히 거부하고, bea cloud login은 사람이 필요하며, 성공적인 bea cloud logout 또는 bea cloud ledger clone은 JSON 성공 객체를 반환하지 않습니다 — 대신 종료 상태를 읽으세요. 도움말, 버전, 셸 완성 출력은 텍스트로 유지됩니다.

다음 단계​

bea로 부기 자동화하기

출처: https://beancount.io/ko/docs/Solutions/automate-bookkeeping-with-bea