Beancount CLI 참조

이 레퍼런스로 bea 명령과 그 동작을 찾아보세요. 첫 원장은 CLI 빠른 시작을 따르세요. 한 달 결산을 처음부터 끝까지 마무리하려면 bea와 함께하는 첫 달을 진행하세요. 은행 파일은 가져오기 안내를 사용하세요.

주요 명령어 한눈에 보기​

전역 옵션 및 경로​

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

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, Expenses:Uncategorized, Equity:OpeningBalances를 엽니다.

개시 잔액은 Equity:OpeningBalances로 상계됩니다. 부채는 음수입니다. 통화 입력은 대문자로 변환됩니다. 사용자 정의 심볼이 허용되며, 세 개의 대문자가 아닌 심볼은 오타 경고를 발생시킵니다. 이는 ISO 통화 레지스트리 검사가 아닙니다.

기존 파일은 절대 덮어쓰지 않습니다. 새 파일은 POSIX에서 소유자 전용 권한, 모드 0600을 사용합니다. 이후 add 및 import 쓰기는 권한을 보존하고 읽기 전용 대상을 존중합니다. 제자리 포맷은 네이티브 포맷터를 사용하며 자체 파일 시스템 오류를 보고합니다.

거래 추가​

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'

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

네이티브 전기 구문은 84/2 EUR 같은 산술, {100 USD} 같은 원가, 총원가 {{1000 USD}}, 가격 @ 또는 @@를 지원합니다. 1e3 같은 지수 표기가 아닌 1000 같은 십진 금액을 사용하세요.

환전에는 실제 거래 환율이 필요합니다. 예를 들어 EUR로 개설된 계정에 100 EUR @ 1.08 USD를, 당좌 계정에 -108 USD를 전기합니다. 투자 매입은 AAPL로 개설된 계정에 2 AAPL {100 USD}를, 당좌 계정에 -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입니다.

전기는 {"number":"45.00","currency":"USD"} 같은 amount 또는 units 중 하나를 사용합니다. 잔액 맞춤 전기는 둘 다 생략합니다. 전기 필드에는 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"

대상은 루트 디렉터리 기준 상대 경로입니다. 이미 포함되어 있어야 하며, 관련 없는 파일을 지정하면 거부됩니다. add 명령, import, 대화형 AI 쓰기가 이 분리를 지원합니다.

쓰기는 플러그인과 원가 로트 부기를 포함한 전체 후보 원장을 검증합니다. 루트나 포함 그래프에 대한 동시 변경은 종료 코드 4로 종료됩니다. 읽기 전용 대상은 종료 코드 3으로 종료됩니다. 성공적인 추가는 새 줄만 정렬합니다. 기존 바이트는 변경되지 않습니다. 파일 전체를 재정렬하려면 bea format -i PATH를 사용하세요.

지시문 목록​

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

다른 지시자 유형은 시간순을 유지합니다. 계정으로 필터링한 거래 표는 금액 열을 MATCHING POSTING AMOUNTS로 표시합니다. Details와 JSON은 선택된 각 거래의 모든 전기를 여전히 포함합니다. Details는 추론된 금액을 포함하여 로드된 항목을 렌더링하며, 원본 소스 발췌가 아닙니다.

검사, 형식화, 쿼리​

bea check는 루트와 포함 파일을 검증합니다. 성공 시 조용히 종료 코드 0, 원장 오류 시 1로 종료됩니다. 전역 --json은 검증 봉투를 반환합니다. check에는 --allow-errors 옵션이 없습니다.

쿼리, 목록, 보고서는 대화형 터미널에서 경고하고 부분 결과를 반환합니다. 전역 --strict, --json, --no-input, 참인 CI, 또는 비터미널 stdin은 읽기를 엄격하게 만듭니다. 이들의 --allow-errors 옵션은 부분 결과를 명시적으로 허용합니다.

포맷은 파일을 받거나 디렉터리를 재귀적으로 검색합니다. 게시된 0.2.0 패키지에서는 도움말에 표시된 stdin 기본값에도 불구하고 경로가 필수입니다. 전역 --file은 포맷 대상을 선택하지 않습니다.

포맷은 텍스트를 정렬하며 원장 구문이나 회계를 검증하지 않습니다. bea check를 별도로 실행하세요. 전역 --json과 함께 사용할 때는 stdout이 봉투를 실을 수 있도록 -i, -o FILE, --check, --dry-run 중 하나를 선택하세요. stdout을 입력 파일로 리디렉션하지 마세요: 재작성하려면 -i를 사용하세요.

bea query "BQL"은 Beancount query를 실행합니다. BQL을 생략하면 stdin에서 쿼리를 읽거나 stdin이 터미널일 때 셸을 엽니다. 셸은 .exit, exit, quit으로 닫습니다. BQL의 기본 표는 전기마다 한 행입니다. 쿼리 표는 정밀도를 유지합니다.

명령 앞에 원장을 선택하세요. 예: bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". 전역 --json은 data.rows와 data.columns가 있는 제품 봉투를 사용하며 CSV 렌더링과는 다릅니다. 게시된 0.2.0 릴리스에서 JSON을 저장하려면 셸 리디렉션을 사용하세요. 예: bea --json query "SELECT account, sum(position) GROUP BY account" > result.json. 그 릴리스에서는 쿼리 -o와 -m이 JSON에 적용되지 않습니다.

네이티브 도구 및 선택적 기능​

bea doctor context main.bean 42는 42번째 줄의 거래 컨텍스트를 보여줍니다. bea doctor --help는 다른 진단 명령을 나열합니다. bea example -o example.bean은 샘플 이력을 만듭니다. bea treeify accounts.txt는 텍스트 파일에서 계층적 이름을 렌더링합니다; 파일을 생략하면 stdin을 읽습니다. 이 명령들은 네이티브 인자를 전달합니다. 위 예제는 그 인자들을 명시적으로 지정합니다.

시세 조회에는 bea engine enable beanprice, 임포터 워크플로에는 bea engine enable beangulp로 선택적 도구를 한 번 활성화하세요. 활성화에는 네트워크 접속이 필요하며, Beangulp는 시스템 libmagic 라이브러리도 필요합니다. bea engine status로 사용 가능 여부를 확인하세요. bea price --help와 bea ingest --help는 각자의 인터페이스를 설명합니다. bea import --csv와 bea add price는 두 선택적 기능 모두 필요하지 않습니다.

관리 가격 포함​

Live Prices는 별도의 관리 포함 워크플로입니다. 호스팅 원장은 지원되는 가격 URL을 확인하며, 호환되는 bea 버전은 관리 포함과 로컬 가격 내보내기도 지원합니다. 설치된 버전이 이 명령들을 인식하지 못하면 버전별 관리 가격 안내를 확인하세요.

CLI는 허용 목록에 있는 관리 URL을 자격 증명을 보내지 않고 확인하며 리디렉션을 거부합니다. 따라서 호스팅 로그인으로 리디렉션하는 피드는 새 로컬 가져오기에서 사용할 수 없으며, 웹사이트 로그인은 CLI 가격 요청을 인증하지 않습니다. 소스 오류는 price status로 조사하세요. 상황에 따라 캐시된 데이터, 접근 가능한 지원 피드, 또는 로컬 날짜 지정 가격을 사용하세요.

price export는 prices/ 아래에 피드 파일을 쓰고 포함 구문을 로컬 상대 경로로 다시 씁니다. 업스트림 Beancount, Fava, Beanquery는 그 내보낸 사본을 로드할 수 있습니다. 사용할 수 없는 소스는 --allow-errors를 사용하지 않으면 내보내기를 거부하며, 이 경우 소스 마커에 가격 없이 남을 수 있습니다.

직접 지정한 날짜 가격은 같은 날짜와 쌍의 관리 가격을 덮어씁니다. 피드 항목은 읽기 전용입니다. 실패한 갱신은 이전에 검증된 리비전을 유지하며, 이는 오래되었을 수 있습니다. bea price의 다른 인자는 여전히 Beanprice로 전달됩니다; 시세 작업 파일 이름이 status이면 하위 명령과 구분하려면 ./status를 전달하세요.

Homebrew는 CLI와 관리 엔진을 모두 설치합니다. PyPI에서는 첫 엔진 기반 명령이 고정된 의존성을 다운로드합니다; uv를 PATH에 유지하고 그 첫 실행에 네트워크 접속을 허용하세요. 이후 로컬 명령은 오프라인으로 엔진을 재사용합니다. 고객은 별도의 Beancount 패키지나 관리할 네이티브 콘솔 스크립트 없이 beancount-io만 설치합니다.

재무 보고서​

모든 보고서는 --conversion / -x, --time / -t, --account / -a, --allow-errors를 받습니다. trial balance를 제외한 모두는 --interval / -i도 받습니다: 기본값 monthly, 또는 quarterly, yearly, weekly, daily.

bea balance [ACCOUNT...]는 대소문자 구분 없는 부분 문자열과 일치하는 계정의 잔액 하위 트리를 출력하며, 아무것도 지정하지 않으면 전체 원장을 출력합니다. --conversion / -x, --time / -t, --allow-errors를 받으며 interval이나 account 옵션은 받지 않습니다.

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

환산은 기본값이 원장의 유일한 운영 통화입니다. 그렇지 않으면 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)이며 이익이면 양수입니다. 같은 관례가 income-statement 기간 행에도 적용됩니다. 대차대조표 조정은 보고서용으로 파생되며 지시자를 쓰지 않습니다. 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 필드가 필요합니다. 전체 지침은 요청 시 로드됩니다. 파일 레이아웃과 예제는 스킬로 bea ask 확장을 참조하세요.

호스팅 원장​

전역 --json과 함께 bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create, bea cloud ledger delete는 표준 봉투를 출력합니다. 로그인은 상호작용이 필요하며, 성공한 로그아웃과 클론은 JSON 성공 객체를 반환하지 않습니다.

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

JSON 및 종료 코드​

전역 --json은 성공 결과를 stdout에 출력합니다:

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

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

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

변경을 다시 시도하기 전에 error.result를 확인하세요. 부분 배치는 승인된 행을 쓸 수 있고, 재귀 포맷은 유효한 파일을 변경할 수 있으며, create-and-clone은 0이 아닌 코드로 종료되기 전에 호스팅 원장을 만들 수 있습니다. jq로 이 봉투를 읽고 이 코드로 분기하는 스크립트는 bea로 부기 자동화를 참조하세요.

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

출력 예외: doctor, example, treeify, Beanprice로 전달된 price 호출, ingest는 전역 --json에서도 네이티브 출력과 종료 상태를 유지합니다; 위 봉투와 종료 분류는 그 전달된 결과를 설명하지 않습니다. 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를 사용하세요. 소스 저장소 레퍼런스에는 추가 예제와 정확한 지시자 모델 정의가 있습니다.