Concept

The Configuration

red-ale's own settings file, for what GnuCash keeps in preferences and user files, against Book options, which live in the book. Where it is, how to read and change a Setting by path, secrets, and the settings you are likely to want.

GnuCash keeps settings in two places. Preferences (Edit > Preferences) belong to the person using GnuCash and are kept outside the book. Book options (File > Properties) belong to the book and travel with it. red-ale keeps the same split.

⚠ Do not call the Configuration a "preference file of the book": it never goes into a book. A preference that GnuCash holds, such as the accounting period, is in red-ale's Configuration. GUI-only preferences (window layout, register look, the Tip of the Day) have nothing to configure.

Where it is

Every red-ale process reads one Configuration file:

The file is read at every use, so a change made by hand or by another process takes effect at once. A change takes a lock on <file>.lock while it reads and rewrites the file, so two processes do not lose each other's changes; the file is written whole and renamed into place, and readable by its owner only.

Settings

A Setting is one value of the Configuration, named by its setting path, the keys joined with .: accountingPeriod.start, import.settings.matchThreshold, quotes.services.alphavantage.key. Paths are typed on command lines, so there is no escaping.

• config.schema returns the JSON Schema of every setting: its type, default and description. formats such as period-bound, commodity-id and decimal are checked.
• config.get reads one setting by path, or the whole Configuration with defaults filled in. It works with no book open. It also lists unknown keys in the file (typos, kept and ignored) and problems with values that do not match the schema.
• config.set changes one or more by path, validated against the schema, all or none. Setting a path to null restores its default.

{"jsonrpc":"2.0","id":1,"method":"config.get","params":{"path":"accountingPeriod.start"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "path": "accountingPeriod.start",
    "value": "year",
    "unknown": [],
    "problems": [],
    "configFile": null
  }
}

red-ale exec config.get '{"path":"accountingPeriod.start"}'

{
  "path": "accountingPeriod.start",
  "value": "year",
  "unknown": [],
  "problems": [],
  "configFile": null
}

{"name":"config.get","arguments":{"path":"accountingPeriod.start"}}

{
  "structuredContent": {
    "path": "accountingPeriod.start",
    "value": "year",
    "unknown": [],
    "problems": [],
    "configFile": null
  }
}

Some Settings are owned by other methods: saved report configurations (reports.saved) and style sheets (reports.styleSheets) change only through the report.* methods, so config.set refuses them.

Secrets and the network

A secret, such as a quote service's API key, is never shown: config.get says only {"set": true} or {"set": false}, and no key appears in a result, error, log or journal. Settings that only a person may change are refused through MCP: quotes.network, which lets quote fetches reach the network (off by default, and the only network red-ale uses), and each quote service's key and keyEnv. Changing them over JSON-RPC, the CLI or by editing the file is allowed. A key is also tied to its service's host: pointing a service at a new host clears its key.

Settings you are likely to want

Book options

book.options reads the options kept in the book, and book.setOptions changes them as GnuCash's Book Options dialog does. An absent option is left alone.

Document numbers are kept separately: counters hold the last number issued for each kind of document or owner (gncInvoice, gncCustomer, ...), with a format such as %.6li. counter.list and counter.set read and change them. ⚠ GnuCash's book options call a counter the previous number: the next ID is one more.