period.set

Set the accounting period or the fiscal year end in red-ale's configuration.

Sets the accounting period's start and end bounds or the fiscal year end (MM-DD) in red-ale's Configuration, and returns the result as period.get does. It changes no book and works with no book open. Use clearFiscalYearEnd: true to remove the fiscal year end.

A fiscal choice (fiscal-year, previous-fiscal-year) is refused with invalid unless a fiscal year end is known, from the Configuration or from the open book's own slot; GnuCash would silently return the epoch.

Examples

Example: with no book.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"period.set","params":{"start":"fiscal-year"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

Request:

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

Response:

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

Command line

red-ale exec --script - <<'EOF'
period.set {"start":"fiscal-year"}
period.set {"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"period.set","arguments":{"start":"fiscal-year"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "…",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

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",
    "fiscalYearEndSource": "config",
    "…": "…"
  }
}

Effect: write, on the Configuration only.

Params

Params of period.set. Absent fields keep their setting.

start (string or null): Start: a relative choice or a YYYY-MM-DD date.
end (string or null): End: a relative choice or a YYYY-MM-DD date.
fiscalYearEnd (string or null): Fiscal year end, MM-DD, for the fiscal-year choices.
clearFiscalYearEnd (boolean): Remove the configured fiscal year end (the open book's fy_end slot, if any, then applies).

Result

The accounting period setting.

start (string, required): Start: a relative choice (today, month, previous-month, quarter, previous-quarter, year, previous-year, fiscal-year, previous-fiscal-year) or a YYYY-MM-DD date.
end (string, required): End, in the same form; a relative choice means the period's last day.
fiscalYearEnd (string or null): The fiscal year end in use (MM-DD), if any.
fiscalYearEndSource (string or null): Where it comes from: config, or book (the open book's fy_end slot).
configFile (string or null): The configuration file, if the setting is kept in one; otherwise it lasts as long as the server.
choices (array of string, required): Every relative choice, in GnuCash's order.