Beancount CLI 참조

이 참조를 사용하여 bea 명령어와 그 동작을 확인하세요. 첫 번째 원장을 만들려면 CLI 빠른 시작을 따르세요. 은행 파일의 경우 가져오기 가이드를 사용하세요.

명령어 한눈에 보기​

전역 옵션 및 경로​

전역 옵션은 명령어 앞에 옵니다:

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

init은 자체 디렉토리/파일 대상을 생성하고 BEA_FILE을 무시합니다. 디렉토리 인수 대신 전역 --file을 허용합니다. format은 자체 위치 대상(기본값: 작업 디렉토리)을 사용합니다. 전역 --file은 포맷 대상을 선택하지 않습니다.

원장 생성​

bea init [DIRECTORY]는 기본적으로 현재 디렉토리를 사용합니다. 디렉토리는 main.bean을 생성합니다; .bean 또는 .beancount 경로는 새 파일의 이름을 직접 지정합니다.

템플릿은 Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees 및 Equity:OpeningBalances를 엽니다.

개설 잔액은 Equity:OpeningBalances에 상쇄됩니다. 부채는 음수입니다. 통화 입력은 대문자로 변환됩니다. 사용자 정의 기호 허용; 세 글자 대문자가 아닌 기호는 오타 경고를 트리거합니다. 이는 ISO 통화 등록 검사가 아닙니다.

기존 파일은 절대 덮어쓰지 않습니다. 새 파일은 소유자 전용 권한, POSIX에서 모드 0600을 사용합니다. 이후 추가, 가져오기 및 포맷 쓰기는 권한을 보존하고 읽기 전용 대상을 존중합니다.

거래 추가​

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'

하나의 posting은 금액을 생략할 수 있습니다. 계정에 허용된 통화가 하나이거나 원장에 호환되는 운영 통화가 하나인 경우 번호가 매겨진 posting은 통화를 생략할 수 있습니다. 그렇지 않으면 기호를 제공하세요.

기본 posting 구문은 84/2 EUR와 같은 산술, {100 USD}와 같은 비용, {{1000 USD}}와 같은 총 비용, @ 또는 @@와 같은 가격을 지원합니다. 1e3과 같은 지수 표기 대신 1000과 같은 십진 금액을 사용하세요.

통화 환전에는 실제 거래 환율이 필요합니다. 예를 들어, EUR로 개설된 계정에 100 EUR @ 1.08 USD를 게시하고 checking에 -108 USD를 게시하세요. 투자 매수는 AAPL로 개설된 계정에 2 AAPL {100 USD}를 게시하고 checking에 -200 USD를 게시할 수 있습니다. 보고서에 시장 평가가 필요하면 날짜가 있는 price 견적을 추가하세요.

메타데이터는 --meta 'receipt:IMG_42.jpg'와 같은 일반 문자열을 허용합니다. 기본 숫자, 부울, 날짜 및 금액은 유형을 유지합니다. 예: --meta 'reviewed:TRUE', --meta 'received:2026-08-03', --meta 'fee:2.50 USD'. 내부 따옴표는 문자열을 강제합니다: --meta 'code:"1234"'. 키는 고유해야 합니다; filename 및 lineno는 예약되어 있습니다.

단일 추가, 일괄 추가 및 가져오기는 payee, narration 및 문자열 메타데이터의 줄 바꿈을 공백으로 대체합니다. 따옴표와 백슬래시는 내용을 유지합니다.

기타 지시문 추가​

이 모든 명령어는 --date YYYY-MM-DD가 필요합니다. 또한 --into FILE 및 --allow-errors를 허용합니다.

계정 이름은 대문자 루트와 콜론으로 구분된 세그먼트를 가집니다. 각 하위 계정은 대문자 또는 숫자로 시작합니다. Beancount는 유니코드 문자와 구성된 루트 이름을 지원합니다.

잔액은 날짜 시작 시 계정을 확인합니다. 허용 오차 구문이 지원됩니다 (예: --amount "1538 ~ 1 EUR"). 허용 오차는 음수가 아니어야 합니다.

add balance --pad-from Equity:OpeningBalances를 사용하여 pad와 잔액 확인을 함께 작성하세요. pad는 기본적으로 전날입니다; --pad-date로 더 이른 날짜를 선택할 수 있습니다. 두 계정 모두 활성 상태여야 합니다. 독립형 pad는 이를 소비할 나중 잔액이 필요합니다. --allow-errors는 중간 상태를 준비할 수 있지만 유효하지 않은 pad 계정을 우회할 수는 없습니다.

add price는 루트 및 포함 항목에서 정확한 날짜/상품/가격 중복을 건너뜁니다. 종료 코드 0으로 기존 위치를 식별합니다. 다른 날짜나 가격은 새 추가입니다.

문서 경로는 지시문이 포함된 파일 옆에 해석됩니다. --into years/2026.bean과 함께 --filename receipt.pdf는 셸 작업 디렉토리 옆의 파일이 아닌 years/receipt.pdf를 의미합니다.

사용자 정의 값 종류는 text, number, amount, account, bool 및 date입니다. 예를 들어, 예산은 --value "text:travel" --value "amount:500 USD"를 사용할 수 있습니다.

일괄 JSON 입력​

bea add transactions --from transactions.json은 JSON 배열을 허용합니다:

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

각 거래는 date 및 postings가 필요합니다. 선택 필드는 flag, payee, narration, tags, links 및 meta입니다.

Posting은 amount 또는 units를 사용합니다 (예: {"number":"45.00","currency":"USD"}). 둘 다 생략하면 균형 posting입니다. Posting 필드에는 cost, price, flag 및 meta도 포함됩니다. 비용은 number 및 currency를 포함하며 선택적 date 및 label이 있습니다. 가격은 number 및 currency를 포함합니다.

소수에는 문자열을 사용하세요. 메타데이터는 일반 문자열과 부울, 또는 {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"}, {"kind":"amount","number":"2.50","currency":"USD"}와 같은 태그된 값을 사용합니다. 선택적 거래 source 위치는 메타데이터로 작성되지 않습니다.

기본값은 원자적 배치입니다: 거부된 행이 있으면 원장이 변경되지 않고 종료 코드 1입니다. --partial은 유효한 하위 집합을 작성하고 행이 거부되면 여전히 종료 코드 1입니다. JSON 오류는 error.result에서 결과를 설명합니다; 행 인덱스는 0부터 시작합니다. 인간이 읽는 행 번호는 1부터 시작합니다.

일괄 추가는 --into 및 --allow-errors를 허용합니다. 중복 제거하지 않습니다. 은행 내보내기 검토에는 bea import를 사용하세요.

분할 원장 및 쓰기 안전​

--file을 루트에 유지하세요. 기존 포함 파일을 선택하려면 --into 추가:

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

대상은 루트 디렉토리에 상대적입니다. 이미 포함되어 있어야 합니다; 관련 없는 파일 이름 지정은 거부됩니다. 추가 명령어, 가져오기 및 대화형 AI 쓰기는 이 분리를 지원합니다.

쓰기는 플러그인 및 비용 로트 예약을 포함한 전체 후보 원장을 검증합니다. 루트 또는 포함 그래프의 동시 변경은 종료 코드 4입니다. 읽기 전용 대상은 종료 코드 3입니다. 성공한 추가는 bea format과 동일한 정렬을 사용하며, 해당 대상의 기존 열을 다시 정렬할 수 있습니다.

지시문 나열​

bea list TYPE은 11가지 유형을 지원합니다: transaction, open, close, balance, pad, note, event, price, commodity, document 및 custom.

다른 지시문 유형은 시간순을 유지합니다. 계정 필터링된 거래 테이블은 금액 열을 MATCHING POSTING AMOUNTS으로 표시합니다. 세부 정보 및 JSON은 여전히 선택된 각 거래의 모든 posting을 포함합니다. 세부 정보는 추론된 금액을 포함한 로드된 항목을 렌더링합니다; 원시 소스 발췌가 아닙니다.

확인, 포맷 및 쿼리​

bea check는 루트 및 포함 항목을 검증합니다. 원장 오류에 대해 종료 코드 1이며 --allow-errors 옵션이 없습니다. 쿼리, 목록 및 보고서도 명시적으로 --allow-errors 옵션을 전달하지 않으면 로더 오류를 거부합니다.

포맷은 .bean/.beancount 파일 또는 디렉토리를 사용합니다. 디렉토리는 재귀적으로 검색됩니다.

모든 모드는 파일 및 줄별 구문 오류를 보고하고 해당 파일을 건너뛰며 종료 코드 1입니다. 재귀적 일반 실행은 유효한 파일을 계속 포맷할 수 있습니다. JSON은 실패 시 error.result 아래에 scanned, formatted, skipped, dry_run 및 check를 보고합니다.

bea query "BQL"은 Beancount 쿼리를 실행합니다. BQL을 생략하면 대화형 셸이 열립니다; exit 또는 quit로 닫습니다. 무인 실행에서는 쿼리 인수가 필요합니다. BQL의 기본 테이블은 posting당 한 행입니다. 쿼리 테이블은 정밀도를 유지합니다. 빈 결과는 stderr에 (no rows)을 출력합니다; JSON은 빈 data.rows와 data.columns의 열 메타데이터를 반환합니다.

재무 보고서​

모든 보고서는 --conversion / -x, --time / -t, --account / -a 및 --allow-errors를 허용합니다. 시산표를 제외한 모든 보고서는 --interval / -i도 허용합니다: 기본 monthly, 또는 quarterly, yearly, weekly, daily.

시간 필터에는 연도, 월, 날짜, 분기, 주 또는 범위가 포함됩니다 (예: 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 또는 "2026-01 - 2026-08"). 상대 기간에는 year, quarter, month, week, day 및 month-1 같은 오프셋이 포함됩니다. 계정 필터는 일치하는 거래의 모든 posting을 유지합니다.

변환은 기본적으로 원장의 유일한 운영 통화입니다. 그렇지 않으면 units가 기본값이 되어 상품을 분리합니다. at_cost는 취득 비용을 사용합니다. at_value는 비용 대체가 있는 시장 가치를 사용합니다.

명시적 통화 변환은 모든 평가 날짜(간격 날짜 포함) 이전 또는 당일의 가격이 필요합니다. 가격 누락 오류는 실제 공백을 명명합니다 (예: No EUR → USD price on or before 2026-01-31). 이후 견적은 이전 공백을 채울 수 없습니다. 역사적으로 적절한 가격을 추가하거나, --conversion units를 사용하거나, 부분 값을 검사하려면 --allow-errors를 선택하세요.

부분 보고서는 소스 통화를 보존하고 결합된 합계를 사용할 수 없음으로 표시합니다. JSON은 valuation: "partial", missing_prices 및 missing_price_dates를 포함합니다. 영향을 받는 순이익/순자산 합계는 요청된 통화에서 null입니다.

수익, 부채 및 자본은 일반적으로 음수 Beancount 부호를 사용합니다. 순이익은 -(income + expenses)이며 이익이면 양수입니다. 동일한 규칙이 손익계산서 기간 행에 적용됩니다. 대차대조표 조정은 보고서에 대해 파생됩니다; 지시문을 작성하지 않습니다. equity_reconciled는 완전한 조정이 가능한지 식별합니다.

보고서 JSON은 기간, 종료일, 기준일, 변환, 계정 필터 및 원장 검증 상태도 식별합니다. 합계를 비교하기 전에 해당 필드를 확인하세요.

선택적 AI 지원​

bea ask는 ask 추가 기능과 bea cloud login 또는 BEA_TOKEN의 Beancount.io 자격 증명이 모두 필요합니다. 기본 Homebrew 설치는 AI 종속성을 생략합니다. Homebrew 사용자는 다음을 실행할 수 있습니다:

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

uv 설치의 경우 beancount-io[ask]를 설치하고 bea ask를 직접 실행하세요. --print / -p는 한 번 답하고 종료합니다. 그렇지 않으면 터미널 세션이 대화형이며 선택적 질문이 입력을 미리 채웁니다. 비대화형 사용은 질문이 필요합니다. JSON 모드는 지원되지 않습니다.

쿼리는 로컬에서 실행됩니다. 질문, 스킬 컨텍스트 및 도구 결과는 호스팅된 Beancount.io AI 서비스로 전송됩니다. 대화형 쓰기는 미리보기, 확인, 검증 및 원자적으로 작성됩니다. --into를 허용합니다. 전역 --yes는 AI 쓰기 권한을 부여하지 않습니다. 일회 답변 모드는 제안된 쓰기를 적용하지 않습니다.

Ask는 작업 디렉토리의 .agents/skills/ 및 사용자 구성 디렉토리의 skills/에서 NAME/SKILL.md를 읽습니다. 프로젝트 정의가 이름으로 우선합니다. 각 파일에는 YAML name 및 description 필드가 필요합니다. 전체 지침은 요청 시 로드됩니다.

호스팅 원장​

생성은 --clone 및 --dir도 허용합니다. 복제에는 Git 및 SSH 접근이 필요합니다. 생성 후 복제가 실패하면 호스팅 원장은 여전히 존재합니다. 로컬 명령어는 원장을 자동으로 업로드하지 않습니다. 전역 --ledger 옵션은 없습니다.

JSON 및 종료 코드​

전역 --json은 성공적인 결과를 stdout에 넣습니다:

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

bea는 설치된 버전입니다; data는 명령어에 따라 다릅니다. 대상은 파일, 디렉토리, 서버 또는 대상 없음을 식별합니다. 포함된 쓰기도 into를 식별합니다. 십진 금액과 날짜는 문자열을 사용합니다. 제한된 목록에는 limit 및 truncated가 포함됩니다.

실패는 stderr에 {"error":{"category":"validation","message":"…","exit_code":1}}를 작성합니다. 오류에는 details, result, 백엔드 request_id 및 --debug로 traceback도 포함될 수 있습니다.

변형을 재시도하기 전에 error.result를 확인하세요. 부분 배치는 허용된 행을 쓸 수 있고, 재귀 포맷은 유효한 파일을 변경할 수 있으며, 생성 및 복제는 0이 아닌 종료 전에 호스팅 원장을 생성할 수 있습니다.

CLI 프롬프트는 --no-input, JSON 모드, 비터미널 stdin 또는 진실된 CI로 비활성화됩니다. 클라우드 삭제는 여전히 명시적 --yes가 필요합니다. 가져오기는 일치 항목 검토가 필요할 때 명시적 중복 결정이 필요합니다.

출력 예외: Ask는 JSON을 거부합니다; 클라우드 로그인은 상호 작용이 필요합니다; 성공적인 클라우드 로그아웃 및 복제는 JSON 성공 객체를 반환하지 않습니다. 도움말, 버전 및 완성은 텍스트 출력을 유지합니다. upgrade는 JSON 모드에서도 패키지 관리자 출력을 stderr로 스트리밍할 수 있습니다.

설정, 업데이트 및 저장된 상태​

진실된 값은 대소문자와 주변 공백을 무시하고 1, true, yes 및 on입니다. 구성 상태에는 자격 증명, Ask 프롬프트 기록, 사용자 스킬, 기억된 가져오기 경로 및 업데이트 확인 캐시가 포함됩니다. 쓰기 잠금은 원장 디렉토리 외부의 캐시 디렉토리 locks/ 아래에 있습니다.

bea upgrade --check는 업그레이드 없이 버전 및 설치 방법을 보고합니다. bea upgrade는 brew upgrade bea, uv tool upgrade beancount-io 또는 pipx upgrade beancount-io를 호출합니다. 편집 가능한 설치는 수동 업데이트 지침을 받습니다. 수동 검사는 대화형 설치 복사본에서 하루에 최대 한 번 실행됩니다; 명시적 upgrade --check는 수동 알리미가 비활성화된 경우에도 실행됩니다.

일치하는 관리자로 제거: brew uninstall bea, uv tool uninstall beancount-io 또는 pipx uninstall beancount-io. 원장 파일과 사용자 구성은 유지됩니다.

일반적인 수정​

설치된 버전을 검사하려면 bea COMMAND --help를 사용하세요. 소스 저장소 참조에는 추가 예제와 정확한 지시문 모델 정의가 있습니다.