Method

book.create

Create a new, empty XML or SQLite book and open it.

Creates a new, empty book (a root account and nothing else) at path and opens it. By default it is an XML book, gzip-compressed as GnuCash writes it; pass compressed: false for plain XML or format: "sqlite" for an SQLite book (also chosen by a sqlite3:// path). The file is written by the first book.save.

The path must be free: an existing file is refused with file-exists, so a book is never overwritten by accident.

Examples

Example: with no book.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.create","params":{"path":"new.gnucash","compressed":false}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "path": "…",
    "guid": "…",
    "rootAccount": "…",
    "readOnly": false,
    "format": "xml",
    "compressed": false,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.list","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "accounts": [],
    "…": "…"
  }
}

Command line

red-ale exec --script - <<'EOF'
book.create {"path":"new.gnucash","compressed":false}
account.list {}
EOF

It prints:

[
  {
    "path": "…",
    "guid": "…",
    "rootAccount": "…",
    "readOnly": false,
    "format": "xml",
    "compressed": false,
    "…": "…"
  },
  {
    "accounts": [],
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"book.create","arguments":{"path":"new.gnucash","compressed":false}}

Result:

{
  "structuredContent": {
    "path": "…",
    "guid": "…",
    "rootAccount": "…",
    "readOnly": false,
    "format": "xml",
    "compressed": false,
    "…": "…"
  }
}

Tool call:

{"name":"account.list","arguments":{}}

Result:

{
  "structuredContent": {
    "accounts": [],
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of book.create.

  • path (string, required): A path, or an xml:// or sqlite3:// URI, that does not exist yet.
  • compressed (boolean or null): XML only: write it gzip-compressed (GnuCash's default). Defaults to the server's setting.
  • format (BookFormat or null): xml or sqlite. Defaults to the one a sqlite3:// or xml:// URI names, else xml.

Result

The result of book.open, book.create and book.info.

  • path (string, required): The book's file.
  • guid (Guid, required): The book's GUID.
  • rootAccount (Guid, required): The root account's GUID.
  • readOnly (boolean, required): Nothing can be changed.
  • readOnlyReasons (array of ReadOnlyInfo, required): Why, when read-only.
  • dirty (boolean, required): There are unsaved changes.
  • compressed (boolean, required): The file is gzip-compressed; always false for an SQLite book.
  • format (BookFormat, required): The file's format: xml or sqlite.
  • versions (array of VersionInfo or null): SQLite books only: the versions table as read, in its order.
  • journal (string or null): The transaction journal being written, if any.
  • features (array of FeatureInfo, required): Book features the book declares.
  • counts (Counts, required): Entity counts.