tx
Manage ledger transactions.
traj tx manages ledger transactions. A transaction is a set of postings that sum to zero, dated
by you: the date is one you pass
(ADR 0018).
Corrections are new transactions: history is never edited
(ADR 0016).
traj tx add
Record a transaction, either from flags or from a JSON transaction document.
--from <string>— the source account’s exact name or id; required--to <string>— the destination account’s exact name or id; required--amount <string>— a magnitude in the accounts’ currency, as a decimal string; required--date <string>— the transaction’sYYYY-MM-DDdate; required--opening—--fromnames the equity account, and--amountis signed: positive funds the destination, negative opens it overdrawn; another kind of account is refusedNON_EQUITY_CONTRA--project <string>— tag every posting with this project--memo <string>— free text kept with the transaction; part of its duplicate identity--external-ref <string>— an idempotency key; replaying it is a duplicate--dry-run— report the transaction and roll the write back--postings <string>— read a JSON transaction document from this path, or-for stdin; see The transaction document
traj tx add --from Cash --to Food --amount 120.50 --date 2026-03-01 # Record a purchase from Cash.
traj tx add --postings - # Read a multi-posting document from stdin. An opening balance
--opening names the equity account in --from and posts --amount against it, and it is how a
ledger gets its first money. The Quickstart creates and funds Opening already; on a ledger of
your own, create the equity account first and then post against it:
traj account add Opening --type equity --currency THB # The equity account an opening balance posts against.
traj tx add --opening --from Opening --to Cash --amount 1000.00 --date 2026-01-01 # Fund Cash: a positive amount.
traj tx add --opening --from Opening --to Cash --amount -25.00 --date 2026-01-01 # Instead of funding it: a negative amount opens Cash already overdrawn. A positive --amount funds the destination; a negative one opens it already overdrawn, and the
sign is always yours to state. An asset opened that way refuses the Baseline with NEGATIVE_AMOUNT
until a posting funds it, as the baseline page explains.
--from must be an equity account. Any other type is refused at exit code 3 with
NON_EQUITY_CONTRA, which names the type it found.
The transaction document
--postings reads a transaction document: the transaction itself, with its postings in the order
they are written. traj tx add and traj tx amend take the same shape. This one records a 60.00
THB purchase paid from Cash, and is the smallest document that runs:
{
"date": "2026-07-01",
"postings": [
{ "account": "Food", "amount": "60.00", "currency": "THB" },
{ "account": "Cash", "amount": "-60.00", "currency": "THB" }
]
} date— required. The transaction’sYYYY-MM-DDdate; an impossible date isINVALID_DATE.postings— required. At least two postings, written in the order they are stored, summing to zero per currency.memo— optional. Free text kept with the transaction; part of its duplicate identity.externalRef— optional. An idempotency key; replaying it is a duplicate.- A posting’s
account— required. The account’s exact name or its id. - A posting’s
amount— required. A signed decimal string in the posting’s currency, such as"60.00"or"-60.00", with debit positive: the postings of one transaction sum to zero, so one side of it is negative. There is no+sign, no thousands separator and no exponent —+60.00,1,000.00and6e1are each invalid input — and a posting of zero is refused. This is not the flag form’s--amount, which is a magnitude except under--opening. - A posting’s
currency— required. The document has no currency of its own and there is no currency flag: each posting names an ISO 4217 code, and this release supports THB only. - A posting’s
dimensions— optional. Tags that change no balance.--project lunchin the flag form is exactly"dimensions": { "project": "lunch" }on each posting.
Unlike a Scenario document, whose amounts are whole numbers of the currency’s smallest unit (Agent), a transaction document’s amounts are decimal strings.
Hand the document over by path, or as - to read it from stdin:
traj tx add --postings receipt.json # Read the document from a file.
traj tx add --postings - < receipt.json # Read the same document from stdin. - is the only way to ask for stdin, and an empty document is invalid input. A file that cannot be
read fails at --postings, before the document is parsed.
A document replaces the flags: the two forms cannot be combined
(ADR 0020).
Beside --postings, traj tx add accepts only --dry-run and refuses its other flags —
traj tx add --postings - --date 2026-07-02 exits 2 with “--postings cannot be combined with
--date”. Global options are not among the refused fields, so --json still applies.
traj tx amend <id> --postings - reads the replacement from the same shape. The document is the
replacement in full: its date is the replacement’s date, and --void-date defaults to that date,
not to --date, which the document form does not take. Beside --postings, traj tx amend keeps
its <id> positional and accepts only --void-date and --dry-run.
The authority for the shape is the release in your hand: traj schema tx add --json prints it as
.document, a JSON Schema, and traj schema tx amend --json prints the same document.
A failure names the document’s path. A document the schema rejects carries a document. prefix:
invalid_input (document.postings.0.currency) for a missing currency, and document.project for
a field the document does not define, so a project belongs in a posting’s dimensions. The checks
that run after the schema name the path without it, such as postings.0.amount for an amount that
is not a plain decimal.
traj tx amend <id>
Reverse a transaction and record its replacement.
--date <string>— the replacement’sYYYY-MM-DDdate; required--void-date <string>— the reversal’sYYYY-MM-DDdate; defaults to--dateand may not precede the original’s date--from <string>— the replacement’s source account’s exact name or id; required--to <string>— the replacement’s destination account’s exact name or id; required--amount <string>— a magnitude in the accounts’ currency, as a decimal string; required--opening—--fromnames the equity account, and--amountis signed: positive funds the replacement’s destination, negative opens it overdrawn; another kind of account is refusedNON_EQUITY_CONTRA--project <string>— tag every replacement posting with this project--memo <string>— free text kept with the replacement--external-ref <string>— the replacement’s new idempotency key; the original’s is a conflict--dry-run— report both rows and roll the write back--postings <string>— read a JSON transaction document for the replacement from this path, or-; see The transaction document
traj tx amend 0194a000-0003-7000-8000-000000000003 --from Cash --to Food --amount 100 --date 2026-03-02
traj tx amend 0194a000-0003-7000-8000-000000000003 --postings - # Read the replacement's postings from stdin. traj tx import [file]
Import transactions from the one CSV template (ADR 0025).
--template— print the CSV template and open no data directory--dry-run— report the import and roll every write back
traj tx import --template # Print the one CSV template.
traj tx import statement.csv # Import a filled template.
traj tx import - --dry-run # Preview a template read from stdin. --template prints exactly the header the importer reads and opens no data directory:
date,from,to,amount,memo,external_ref,project A file you write starts with that same header and one row per transaction. amount is a positive
magnitude in the destination account’s currency, and external_ref is required: it is the duplicate
key, so prefix it with its source.
date,from,to,amount,memo,external_ref,project
2026-03-01,Cash,Food,120.50,Groceries,kbank:2026-03-01-0001,lunch traj tx list
List transactions by date. Date ranges are --since and --until, both inclusive
(ADR 0022).
--since <string>— the earliest transaction date, inclusive, asYYYY-MM-DD--until <string>— the latest transaction date, inclusive, asYYYY-MM-DD--account <string>— an account’s exact name or id; a posting on either side matches--project <string>— a project dimension value; only the postings carrying it are returned
traj tx list --json # Read the whole ledger as JSON.
traj tx list --since 2026-01-01 --until 2026-03-31 # Read one inclusive date range.
traj tx list --account Cash --project lunch # Transactions touching Cash, narrowed to their lunch postings. traj tx show <id>
Show one transaction with its postings and corrections.
traj tx show 01940000-0000-7000-8000-000000000000 --json # Show a transaction by id. traj tx void <id>
Reverse a transaction, keeping both rows.
--date <string>— the reversal’sYYYY-MM-DDdate; it may not precede the original’s; required--dry-run— report the reversal and roll the write back
traj tx void 0194a000-0003-7000-8000-000000000003 --date 2026-03-02 # Reverse a transaction by id.
traj tx void 0194a000-0003-7000-8000-000000000003 --date 2026-03-02 --dry-run # Show the reversal without writing it. Decisions
- ADR 0016: deletion has three names, and only one is a tombstone
- ADR 0019:
--dry-runexecutes the write and rolls it back - ADR 0020: a leaf may declare a document schema, and
-reads it from stdin - ADR 0022: date ranges are
--sinceand--until - ADR 0025: CSV import is one template, one transaction, keyed by external reference
See Commands for the global options, exit codes and error envelope.