Configure red-ale

Change red-ale's own settings (accounting period, report directory, network) with config.set, and the settings stored in the book with book.setOptions.

There are two places where settings live, and it matters which you change.

The Configuration belongs to you and your machine: the accounting period that reports default to, the folder of your User reports, whether the network may be used for online quotes, import settings and limits. It is a JSON file (by default ~/.config/red-ale/config.json), shared by every book you open. This is what GnuCash calls preferences.
Book options belong to the book and travel with it: the company's name and details, whether to use trading accounts, the auto read-only threshold, which source the number field uses, the default budget. GnuCash stores them in the file, so GnuCash sees them too.

Steps

See what can be set with config.schema: every setting, its type, default and description. config.get returns the current values; give a path such as quotes.network for one. Secrets (such as quote service keys) are shown only as set or unset.
Change settings with config.set: changes maps a path to its new value, and null restores a default. The whole call is checked first: a bad path or value changes nothing and the error names it (invalid-params). Neither call needs a book to be open. Over MCP the network setting cannot be changed.
Set the accounting period with period.set: start and end, each a relative choice (year, previous-month, fiscal-year, ...) or a date, and fiscalYearEnd as MM-DD for the fiscal-year choices. period.get reads it, and period.dates shows the first and last day it works out to for today, or a date you give. Reports use it for relative dates.
Point to your report scripts with reports.directory (Write your own report).
Allow the network only if you want online quotes (Record prices and commodities): {"changes": {"quotes.network": true}}.
Change book options with book.setOptions and read them with book.options. Set only the ones you want to change. For the business options, see Set up the business features. The changes are made in memory and kept when you save the book.
Use another file for a run with red-ale --config <file> or --no-config on the command line, which keeps the settings in memory for that process only.

Example

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-07-01T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"config.schema","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "title": "red-ale Configuration",
    "type": "object",
    "properties": {
      "…": "…"
    },
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"config.set","params":{"changes":{"quotes.network":true}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "values": {
      "quotes.network": true
    },
    "clearedKeys": [],
    "configFile": null
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"config.get","params":{"path":"quotes.network"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "path": "quotes.network",
    "value": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":4,"method":"period.set","params":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "start": "fiscal-year",
    "end": "fiscal-year",
    "fiscalYearEnd": "03-31",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"book.setOptions","params":{"autoReadOnlyDays":30}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "autoReadOnlyDays": 30,
    "readOnlyThreshold": "2024-06-01",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":6,"method":"book.options","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "autoReadOnlyDays": 30,
    "useTradingAccounts": false,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
config.schema {}
config.set {"changes":{"quotes.network":true}}
config.get {"path":"quotes.network"}
period.set {"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}
book.setOptions {"autoReadOnlyDays":30}
book.options {}
EOF

It prints:

[
  {
    "title": "red-ale Configuration",
    "type": "object",
    "properties": {
      "…": "…"
    },
    "…": "…"
  },
  {
    "values": {
      "quotes.network": true
    },
    "clearedKeys": [],
    "configFile": null
  },
  {
    "path": "quotes.network",
    "value": true,
    "…": "…"
  },
  {
    "start": "fiscal-year",
    "end": "fiscal-year",
    "fiscalYearEnd": "03-31",
    "…": "…"
  },
  {
    "autoReadOnlyDays": 30,
    "readOnlyThreshold": "2024-06-01",
    "…": "…"
  },
  {
    "autoReadOnlyDays": 30,
    "useTradingAccounts": false,
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"config.schema","arguments":{}}

Result:

{
  "structuredContent": {
    "title": "red-ale Configuration",
    "type": "object",
    "properties": {
      "…": "…"
    },
    "…": "…"
  }
}

Tool call:

{"name":"config.set","arguments":{"changes":{"quotes.network":true}}}

Result:

{
  "structuredContent": {
    "values": {
      "quotes.network": true
    },
    "clearedKeys": [],
    "configFile": null
  }
}

Tool call:

{"name":"config.get","arguments":{"path":"quotes.network"}}

Result:

{
  "structuredContent": {
    "path": "quotes.network",
    "value": true,
    "…": "…"
  }
}

Tool call:

{"name":"period.set","arguments":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}}

Result:

{
  "structuredContent": {
    "start": "fiscal-year",
    "end": "fiscal-year",
    "fiscalYearEnd": "03-31",
    "…": "…"
  }
}

Tool call:

{"name":"book.setOptions","arguments":{"autoReadOnlyDays":30}}

Result:

{
  "structuredContent": {
    "autoReadOnlyDays": 30,
    "readOnlyThreshold": "2024-06-01",
    "…": "…"
  }
}

Tool call:

{"name":"book.options","arguments":{}}

Result:

{
  "structuredContent": {
    "autoReadOnlyDays": 30,
    "useTradingAccounts": false,
    "…": "…"
  }
}