Method

budget.copy

Copy a budget as GnuCash's Copy Budget does (notes are not copied).

Copies a budget as GnuCash's Copy Budget does: a new budget named Copy of <name> with the same description, recurrence, number of periods and every amount. Notes are not copied, nor are amounts hidden beyond the period count, and the copy goes last in book order. Rename it with budget.update.

Examples

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Response:

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

Request:

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

Response:

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

Request:

{"jsonrpc":"2.0","id":3,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":0,"amount":"750.00"}]}}

Response:

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

Request:

{"jsonrpc":"2.0","id":4,"method":"budget.setNotes","params":{"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":"New lease"}]}}

Response:

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

Request:

{"jsonrpc":"2.0","id":5,"method":"budget.copy","params":{"budget":"00ed0000000000000000000000000002"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "name": "Copy of 2024",
    "isDefault": false,
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "75000",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "notes": [],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Rent","type":"EXPENSE","commodity":"USD"}
budget.create {"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}
budget.setAmounts {"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":0,"amount":"750.00"}]}
budget.setNotes {"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":"New lease"}]}
budget.copy {"budget":"00ed0000000000000000000000000002"}
EOF

It prints:

[
  "…",
  "…",
  "…",
  "…",
  {
    "name": "Copy of 2024",
    "isDefault": false,
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "75000",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "notes": [],
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Result:

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

Tool call:

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

Result:

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

Tool call:

{"name":"budget.setAmounts","arguments":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":0,"amount":"750.00"}]}}

Result:

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

Tool call:

{"name":"budget.setNotes","arguments":{"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":"New lease"}]}}

Result:

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

Tool call:

{"name":"budget.copy","arguments":{"budget":"00ed0000000000000000000000000002"}}

Result:

{
  "structuredContent": {
    "name": "Copy of 2024",
    "isDefault": false,
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "75000",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "notes": [],
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Names one budget.

  • budget (Guid, required): The budget.

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.