# 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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0018-no-clock-in-ledger-commands.md)).
Corrections are new transactions: history is never edited
([ADR 0016](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0016-three-deletion-stories.md)).

## `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](#the-transaction-document)

```bash
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:

```bash
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](https://trajectonomics.com/docs/cli/commands/baseline/) 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:

```json
{
  "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](https://trajectonomics.com/docs/cli/agent/)), a transaction document's amounts are decimal strings.

Hand the document over by path, or as `-` to read it from stdin:

```bash
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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0020-a-leaf-may-declare-a-document-schema.md)).
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](#the-transaction-document)

```bash
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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0025-csv-import-is-one-template.md)).

- `--template` — print the CSV template and open no data directory
- `--dry-run` — report the import and roll every write back

```bash
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:

```csv
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.

```csv
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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0022-date-ranges-are-since-and-until.md)).

- `--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

```bash
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.

```bash
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

```bash
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](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0016-three-deletion-stories.md)
- [ADR 0019: `--dry-run` executes the write and rolls it back](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0019-dry-run-executes-and-rolls-back.md)
- [ADR 0020: a leaf may declare a document schema, and `-` reads it from stdin](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0020-a-leaf-may-declare-a-document-schema.md)
- [ADR 0022: date ranges are `--since` and `--until`](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0022-date-ranges-are-since-and-until.md)
- [ADR 0025: CSV import is one template, one transaction, keyed by external reference](https://github.com/trajectonomics/cli/blob/v0.2.0/docs/adr/0025-csv-import-is-one-template.md)

See [Commands](https://trajectonomics.com/docs/cli/commands/) for the global options, exit codes and error envelope.

Part of the [Docs index](https://trajectonomics.com/docs/llms.txt).
