book.save

Save the open book, backing up the previous file first (for an SQLite book, before the session's first save).

Writes the open book to its file. Changes made by other methods live in memory (and in the .log journal) until you call this. Before overwriting, it copies the previous file to <book>.<timestamp>.gnucash, as GnuCash does, and returns the copy's path as backup; it then reads the new file back to check that it holds the same book.

An XML book keeps its compression unless you pass compressed. An SQLite book is backed up before the session's first save that writes, and compressed is refused for it.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"book.info","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "dirty": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"book.save","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "backup": "…",
    "removed": [],
    "compressed": false
  }
}

Request:

{"jsonrpc":"2.0","id":4,"method":"book.info","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "dirty": false,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}
book.info {}
book.save {}
book.info {}
EOF

It prints:

[
  "…",
  {
    "dirty": true,
    "…": "…"
  },
  {
    "backup": "…",
    "removed": [],
    "compressed": false
  },
  {
    "dirty": false,
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

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

Result:

{
  "structuredContent": {
    "dirty": true,
    "…": "…"
  }
}

Tool call:

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

Result:

{
  "structuredContent": {
    "backup": "…",
    "removed": [],
    "compressed": false
  }
}

Tool call:

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

Result:

{
  "structuredContent": {
    "dirty": false,
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of book.save.

compressed (boolean or null): XML only: change the file's compression; by default it is kept.

Result

What book.save did.

backup (string or null): The backup of the previous file.
removed (array of string, required): Old backups and journals removed by retention.
compressed (boolean, required): The file was written gzip-compressed; always false for an SQLite book.