book.close

Close the open book and release its lock.

Closes the open book and releases its lock, so another program (or another book.open) can use it. If the book has unsaved changes the call is refused with unsaved-changes and the book stays open; pass save: true to write them first or discard: true to drop them.

Not to be confused with book.closeBooks, which is GnuCash's Close Book: it zeroes income and expense into equity and leaves the book open.

Examples

An edited book will not close until you say what to do with the edit:

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.close","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 1012,
    "message": "…",
    "data": {
      "help": "error/unsaved-changes"
    }
  }
}

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "saved": true,
    "discarded": false
  }
}

Command line

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

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

{
  "error": {
    "code": 1012,
    "message": "…",
    "data": {
      "help": "error/unsaved-changes"
    }
  }
}

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.close","arguments":{}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 1012,
      "name": "unsaved-changes",
      "message": "…",
      "data": {
        "help": "error/unsaved-changes"
      }
    }
  }
}

Tool call:

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

Result:

{
  "structuredContent": {
    "saved": true,
    "discarded": false
  }
}

Effect: write, on the Book.

Params

Params of book.close.

save (boolean): Save unsaved changes first.
discard (boolean): Discard unsaved changes. Without save or discard, closing a book with unsaved changes is refused.

Result

What book.close did.

saved (boolean, required): The book was saved before closing.
discarded (boolean, required): Unsaved changes were discarded.