augr

Finance Script Reference

An augr finance script is a UTF-8 encoded file containing a list of directives. A new line will begin a new directive, unless it is inside parentheses (), a list [], or a closure {}.

For example, each line here is treated as a separate directive:

currency USD 2

# indentation doesn't matter
   open IndentedAccount 2025-06-26

# This will generate an error as `assert_balance` requires 4 parameters
assert_balance
  2025-06-26       # These parameters are instead parsed as separate directives.
  IndentedAccount  # They would also generate an error, since they aren't valid directives.
  123.00
  USD

This will treated as a single directive since it is enclosed with parentheses:

(assert_balance
  2025-06-26
  IndentedAccount
  123.00
  USD)

This will be treated as a single directive because the list extends over multiple lines:

transaction 2020-01-01T00:00:00Z [ # a list opens on this line
  [StartingBalance  -3071.64 USD]
  [Assets:Checking   3071.64 USD]
]                                  # and doesn't close until this line

Directives

Directives are order independent*.

*add_ofx_transaction_rule is not order independent. Only the first ofx_transaction_rule that a transaction matches will be used, later rules will be ignored.

In the future this will be treated as an error instead.

currency

currency <name> <num-decimal-points>

name is an arbitrary string. However ISO 4217 three letter currency codes are recommended in general, and required if the currency appears in an imported OFX file.

num-decimal-points is the number of digits after the decimal point. This value is not used at the moment.

See also:

Examples:

currency USD 2
currency EUR 2
currency ETH 18

open

open <name> <datetime> [currency-restriction]...

Opens an account at the given datetime. Colons (’:’) in an account name indicate a nested account.

It is recommended for the root of each account to be one of Assets, Liabilities, Income, or Expenses; however the root of the account currently has no effect on what augr finance outputs.

See also Explanation - Account Names.

In the future the conventional root accounts will be used to filter reports.

Account opening dates are not currently enforced.

Account currency restrictions are not currently enforced.

All the parameters after the name and datetime are treated as currency restrictions at the moment. A future version will change it to take a list instead.

Parent accounts must be specfied before child accounts to be tracked as the parent of the child account.

Each child account opened will only add data for it’s immediate parent; Assets:US:Chase:Checking will look for Assets:US:Chase to add it as a parent, but not Assets or Assets:US. However if Assets:US:Chase already has Assets:US listed as a parent, and Assets:US has Assets, the information will be utilized correctly.>

This will be fixed in a future version.

Examples:

open Assets:US:Checking 2025-06-20 USD
open Expenses:Food 1998-01-01

transaction

transaction <datetime> <postings>

Adds a transaction at the given time with the given postings.

Postings are in the format [<account-name> <amount> <currency-name>], and may also contain key value pairs.

Supported keys:

Examples:

transaction 2020-01-01T00:00:00Z [
  [StartingBalance  -3071.64 USD]
  [Assets:Checking   3071.64 USD]
]

transaction 2021-04-06T12:00:00Z [
  [Assets:Checking  -30.85  USD
    ofx_acctid="4178265997788766926" ofx_fitid="202104060" # Link posting to ofx transaction
  ]
  [Expenses:Food     30.85  USD]
]

close

close <name> <datetime>

Closes an account at the given datetime.

Account closing dates are not currently enforced, or used for anything really. In the future, referencing an account after the date it’s closed will generate an error. It will also hide the account from reports after that date.

Examples:

close Assets:US:Checking 2025-06-20

assert_balance

assert_balance <datetime> <account-name> <amount> <currency-name>

Generates an error if the account does not have the given amount at the given datetime.

See also assert_delta.

Examples:

assert_balance 2024-12-19T12:00:00Z Assets:Checking 2106.76 USD

assert_delta

assert_delta <start-datetime> <end-datetime> <account-name> <amount> <currency-name>

Generates an error if the account does not change the given amount between the start and end datetimes.

See also assert_balance.

Examples:

assert_delta 2023-01-01T00:00:00Z 2023-12-31T23:59:59Z Income:Freelancing -24_704.68 USD

import_ofx

import_ofx <filepath>

Import transactions and balance assertions from an OFX file. Transactions with the same acctid and fitid will be deduplicated.

OFX specifies that its currency symbols are ISO 4217 three letter codes. However, augr finance currently just uses currency directives from the user. Therefore to use import_ofx you must use ISO 4217 currency codes.

Examples:

import_ofx ./Chase_Activity_2025.QFX

map_ofx_id_to_account

map_ofx_id_to_account <ofx-acctid> <account-name>

Maps an OFX acctid to an account name. This will be used to generate transactions from OFX files.

See also:

Examples:

map_ofx_id_to_account "4178265997788766926" Assets:Checking

add_ofx_transaction_rule

add_ofx_transaction_rule <account-name> <ofx-name-rule> [ofx-memo-rule]

If an OFX transaction’s name contains the ofx-name-rule string, it will add a transaction posting with the given account-name with an amount equal to the opposite of the OFX transaction’s amount.

If ofx-memo-rule is provided, the OFX transaction must also have a memo field that contains the ofx-memo-rule string.

See also:

Examples:

add_ofx_transaction_rule Cash "ATM WITHDRAWAL"

OFX transactions can have both a name and memo. Sometimes, it’s a single string split between fields.

add_ofx_transaction_rule Expenses:Entertainment:Games "HUMB" "LEBUNDL"

add_ofx_bidi_rule

add_ofx_bidi_rule <ofx-acctid1> <ofx-transaction-name1> <ofx-acctid2> <ofx-transaction-name2> <max-duration-between>

Generates a transaction based on the data from two OFX accounts if:

  1. The OFX acctids match the given acctids,
  2. The OFX transaction names contain the given text,
  3. The transaction amounts match (for example, one is 123.00 and two is -123.00),
  4. The date_posted of the OFX transactions are within a given duration of each other, and
  5. There are no other OFX transactions that match the previous criteria.

See also:

Examples:

(add_ofx_bidi_rule
    "4178265997788766926"        # OFX acctid 1
    "CREDIT CRD AUTOPAY"         # OFX transaction name for account 1
    "996790420194127215"         # OFX acctid 2
    "AUTOMATIC PAYMENT - THANK"  # OFX transaction name for account 2
    (3 * 86400)                  # Max duration allowed in seconds; 3 days in this case.
)

on_match_add_postings

on_match_add_postings {posting.account contains <string-account-must-contain>} {[
  # Zero or more new postings to add
  [<new-posting-account-name> (posting.amount * <multiplier>) <currency-name>]
]}

Generates an error if the account does not have the given amount at the given datetime.

The current implementation is inflexible:

This directive is experimental, and may be removed in a future version.

Examples:

on_match_add_postings {posting.account contains Income:Freelancing} {[
   [Expenses:Tax (posting.amount * -0.15) USD]
   [Liabilities:Tax:Estimated (posting.amount * 0.15) USD]
]}