Skip to Content
Commands

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’s YYYY-MM-DD date; required
  • --opening — --from names the equity account, and --amount is signed: positive funds the destination, negative opens it overdrawn; another kind of account is refused NON_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’s YYYY-MM-DD date; an impossible date is INVALID_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.00 and 6e1 are 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 lunch in 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’s YYYY-MM-DD date; required
  • --void-date <string> — the reversal’s YYYY-MM-DD date; defaults to --date and 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 — --from names the equity account, and --amount is signed: positive funds the replacement’s destination, negative opens it overdrawn; another kind of account is refused NON_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, as YYYY-MM-DD
  • --until <string> — the latest transaction date, inclusive, as YYYY-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’s YYYY-MM-DD date; 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

See Commands for the global options, exit codes and error envelope.