Run and export a report

Find a report, read its options, run it for exact figures, export it as HTML or CSV, save a set of options under a name, and choose a style sheet.

A report summarises the book: a balance sheet, an income statement, a transaction listing. In red-ale a report is a template with options. You choose a template, set the options you care about, and run it. The result is data: every figure is exact and comes with its display form, so a program can use it and a person can read it. To read it as a page, export it as HTML.

Steps

Find the report. report.list lists the report templates, each with its name and GUID, and any saved configurations. The reports are described in the manual's Reports section (for example Balance Sheet). problems lists user scripts that did not load.
Read its options. report.options gives each option's section, name, type, default and help text, and a JSON Schema for the options param.
Run it with report.run. Give options only for the ones you change, as {"Section": {"Name": value}}. Dates are {"absolute": "2024-03-31"} or {"relative": "end-this-month"}. "Today" is the session's clock unless you give now. A wrong option name or value is refused with a report-option error that names it.
Export it. report.export gives the same report as one self-contained HTML page, with no script and no outside resource. report.exportCsv gives CSV for the reports that have one. The CLI's --output writes either to a file on your side.
Save the options you used with report.saveConfiguration, under a new name. This is GnuCash's saved report configuration. Run it again by name with report.run. Saved configurations live in red-ale's configuration, not in the book.
Choose how it looks. The General/Stylesheet option names a style sheet; report.styleSheets lists them. Pass styleSheet to report.export to use another for one export.
To print on paper, open the HTML in a browser, or turn it into a PDF.

Example

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.options","params":{"report":"Balance Sheet"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "options": "…",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "title": " Balance Sheet 12/31/78",
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"report.export","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "title": " Balance Sheet 12/31/78",
    "html": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":4,"method":"report.saveConfiguration","params":{"name":"Balance sheet 1978","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "name": "Balance sheet 1978",
    "kind": "saved",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"report.run","params":{"report":"Balance sheet 1978"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "title": " Balance Sheet 12/31/78",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
report.options {"report":"Balance Sheet"}
report.run {"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}
report.export {"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}
report.saveConfiguration {"name":"Balance sheet 1978","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}
report.run {"report":"Balance sheet 1978"}
EOF

It prints:

[
  {
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "options": "…",
    "…": "…"
  },
  {
    "title": " Balance Sheet 12/31/78",
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  },
  {
    "title": " Balance Sheet 12/31/78",
    "html": "…"
  },
  {
    "name": "Balance sheet 1978",
    "kind": "saved",
    "…": "…"
  },
  {
    "title": " Balance Sheet 12/31/78",
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"report.options","arguments":{"report":"Balance Sheet"}}

Result:

{
  "structuredContent": {
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "options": "…",
    "…": "…"
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Result:

{
  "structuredContent": {
    "title": " Balance Sheet 12/31/78",
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "sections": "…",
    "…": "…"
  }
}

Tool call:

{"name":"report.export","arguments":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Result:

{
  "structuredContent": {
    "title": " Balance Sheet 12/31/78",
    "html": "…"
  }
}

Tool call:

{"name":"report.saveConfiguration","arguments":{"name":"Balance sheet 1978","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Result:

{
  "structuredContent": {
    "name": "Balance sheet 1978",
    "kind": "saved",
    "…": "…"
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Balance sheet 1978"}}

Result:

{
  "structuredContent": {
    "title": " Balance Sheet 12/31/78",
    "…": "…"
  }
}

A report with CSV output gives its figures as text:

Example: with a copy of the reports/category-daily example book open as book.gnucash, at 2024-03-15T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.exportCsv","params":{"report":"Income Over Time","options":{"Accounts":{"Accounts":["a0000000000000000000000000000003"]},"General":{"Start Date":{"absolute":"2024-03-01"},"End Date":{"absolute":"2024-03-31"},"Step Size":"WeekDelta"}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "title": "",
    "csv": "\"Date\",\"account-3\"\n\"2024-03-01\",28.0\n\"2024-03-08\",77.0\n\"2024-03-15\",126.0\n\"2024-03-22\",175.0\n\"2024-03-29\",90.0"
  }
}

Command line

red-ale exec --book book.gnucash report.exportCsv '{"report":"Income Over Time","options":{"Accounts":{"Accounts":["a0000000000000000000000000000003"]},"General":{"Start Date":{"absolute":"2024-03-01"},"End Date":{"absolute":"2024-03-31"},"Step Size":"WeekDelta"}}}'

It prints:

{
  "title": "",
  "csv": "\"Date\",\"account-3\"\n\"2024-03-01\",28.0\n\"2024-03-08\",77.0\n\"2024-03-15\",126.0\n\"2024-03-22\",175.0\n\"2024-03-29\",90.0"
}

MCP tool call

Tool call:

{"name":"report.exportCsv","arguments":{"report":"Income Over Time","options":{"Accounts":{"Accounts":["a0000000000000000000000000000003"]},"General":{"Start Date":{"absolute":"2024-03-01"},"End Date":{"absolute":"2024-03-31"},"Step Size":"WeekDelta"}}}}

Result:

{
  "structuredContent": {
    "title": "",
    "csv": "\"Date\",\"account-3\"\n\"2024-03-01\",28.0\n\"2024-03-08\",77.0\n\"2024-03-15\",126.0\n\"2024-03-22\",175.0\n\"2024-03-29\",90.0"
  }
}