Method

budget.create

Create a budget; the first sets the Book feature for natural signs.

Creates a budget: a name, a number of periods (1 to 60, default 12) and a recurrence that dates them (default every month from the first of this month). It has no amounts yet; fill them with budget.setAmounts.

The first budget in a book sets the book feature Use natural signs in budget amounts, as GnuCash's New Budget does. In a book that has budgets but lacks the feature, which GnuCash older than 3.8 wrote, creating (and every other edit) is refused with conflict until budget.scrubSigns has run: red-ale never changes budgets when it opens a book. GnuCash's New Budget also fills the description with Created: <date>; red-ale does not, send it yourself if you want it.

Examples

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "name": "2024",
    "numPeriods": 6,
    "isDefault": true,
    "periods": [
      {
        "index": 0,
        "startDate": "2024-01-01",
        "endDate": "2024-01-31"
      },
      {
        "index": 1,
        "startDate": "2024-02-01",
        "endDate": "2024-02-29"
      },
      "…"
    ],
    "amounts": [],
    "notes": [],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"numPeriods":61}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2001,
    "message": "a budget has 1 to 60 periods, not 61",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
budget.create {"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}
budget.create {"numPeriods":61}
EOF

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

{
  "error": {
    "code": 2001,
    "message": "a budget has 1 to 60 periods, not 61",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"budget.create","arguments":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Result:

{
  "structuredContent": {
    "guid": "…",
    "name": "2024",
    "numPeriods": 6,
    "isDefault": true,
    "periods": [
      {
        "index": 0,
        "startDate": "2024-01-01",
        "endDate": "2024-01-31"
      },
      {
        "index": 1,
        "startDate": "2024-02-01",
        "endDate": "2024-02-29"
      },
      "…"
    ],
    "amounts": [],
    "notes": [],
    "…": "…"
  }
}

Tool call:

{"name":"budget.create","arguments":{"numPeriods":61}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "a budget has 1 to 60 periods, not 61",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of budget.create; absent fields take GnuCash's defaults.

  • name (string or null): The name; Unnamed Budget when absent.
  • description (string or null): The description; empty when absent.
  • numPeriods (integer (uint32) or null): The number of periods, 1 to 60; 12 when absent.
  • recurrence (Recurrence or null): The periods' recurrence: never once, weekend adjustment none. Monthly from the first of the current month when absent.

Result

A budget.

  • guid (Guid, required): Identity.
  • name (string, required): The name.
  • description (string, required): The description.
  • numPeriods (integer (uint32), required): The number of periods.
  • recurrence (Recurrence, required): The recurrence that gives the periods' dates, as stored.
  • isDefault (boolean, required): True for the default budget.
  • periods (array of PeriodInfo or null): Each period below numPeriods; absent in budget.list.
  • amounts (array of AmountInfo or null): Every set amount of an account in the tree below numPeriods, by account full name then period; absent in budget.list.
  • notes (array of NoteInfo or null): Every note likewise; absent in budget.list.
  • hidden (SlotCounts, required): Amounts and notes kept at or beyond numPeriods.
  • orphaned (SlotCounts, required): Amounts and notes kept for GUIDs that name no account.