@slothmoney/agent-cli 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-08-12
+
+- Read each goal's one-based priority and move one goal to a new position with
+  automatic shifting of the intervening goals.
+
+## 0.7.0 - 2026-08-09
+
+- Read personal or joint budget periods with categories, line items, funding,
+  and planned amounts.
+- Preview or apply planned line-item updates that overwrite the selected period
+  and all explicit future plans.
+
 ## 0.6.0 - 2026-08-08
 
 - Expose goal-savings membership on account inventory rows and preview or apply

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect accounts and investment holdings, manage goals, and categorise transactions through the
+Use your own agent to inspect accounts, investments, and budgets, manage goals, update planned amounts, and categorise transactions through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.6.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.8.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -25,9 +25,9 @@ Create a personal access token in Sloth Money under
 where the CLI runs.
 
 New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`,
-`categories`, `transactions`, and `goals` list. Enable **Allow changes** when
+`budget`, `categories`, `transactions`, and `goals` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
-or line items, change goal-savings account membership, ask a partner for an explanation, or manage goals. Token
+or line items, update planned budgets, change goal-savings account membership, ask a partner for an explanation, or manage goals. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -103,6 +103,8 @@ options, output, and examples:
 ```bash
 sloth-agent auth login --help
 sloth-agent accounts --help
+sloth-agent budget --help
+sloth-agent budget update --help
 sloth-agent categories --help
 sloth-agent categories create --help
 sloth-agent line-items create --help
@@ -184,6 +186,53 @@ query. Assignments do not create a separate list.
 
 ### Other workflows
 
+Read a personal or joint budget. Omit `--period` to use Sloth's current budget period:
+
+```bash
+sloth-agent budget --scope personal --period 2026-08
+```
+
+The result includes the budget period and status, currency, the effective plan,
+stored funding amounts when available, categories, line items, and planned
+amounts in pence.
+
+Update selected line-item amounts by creating `budget.json`:
+
+```json
+{
+  "allocations": [
+    {
+      "categoryId": "groceries",
+      "lineItemId": "weekly",
+      "plannedPence": 45000
+    }
+  ]
+}
+```
+
+Preview locally, then apply the same file:
+
+```bash
+sloth-agent budget update \
+  --scope personal \
+  --period 2026-08 \
+  --input budget.json
+
+sloth-agent budget update \
+  --scope personal \
+  --period 2026-08 \
+  --input budget.json \
+  --apply
+```
+
+The update starts from the complete selected-period budget, changes the listed
+line items, then overwrites the selected period and every explicit future plan
+with that complete result. A later update from another period overwrites that
+period and everything after it. Earlier and historical periods remain unchanged.
+
+Without `--apply`, the CLI validates the file locally and does not load a token
+or contact Sloth Money. Applying requires a write-enabled token.
+
 Create or rename a custom category. Writes are previews until `--apply` is
 present:
 
@@ -306,7 +355,7 @@ sloth-agent goals create \
   --apply
 ```
 
-Use the `id` from list or create output to update or delete a goal:
+Use the `id` from list or create output to update or delete goals:
 
 ```bash
 sloth-agent goals update \
@@ -316,6 +365,11 @@ sloth-agent goals update \
   --achieved=false \
   --apply
 
+sloth-agent goals update \
+  --goal-id house-goal-id \
+  --priority 2 \
+  --apply
+
 sloth-agent goals delete --goal-id goal-id --apply
 ```
 
@@ -324,7 +378,13 @@ remove an optional value. Marking a goal achieved removes its forecast
 assignment. Deleting a goal also removes its forecast assignments and drift
 history. Goal sharing remains app-managed. Change an active shared goal's
 pot-tracked target amount in the Sloth Budget app, where account balances can
-be reallocated across goals in priority order.
+be reallocated across goals in priority order. Goal list output includes a
+one-based `priority`; `1` is highest. Moving one goal automatically shifts the
+goals between its old and new positions. The
+priority option must be used on its own, and the write persists immediately.
+Forecast assignments and shared pot
+progress are browser-owned derived state and refresh when the owner next opens
+the Forecast screen.
 
 Read uncategorised contributions to the joint budget:
 

package/dist/args.js

@@ -64,6 +64,16 @@ function parseGoalMonthKey(value, name) {
     }
     return value;
 }
+function parseGoalPriority(value) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new UsageError('--priority must be a positive whole-number position');
+    }
+    const priority = Number(value);
+    if (!Number.isSafeInteger(priority)) {
+        throw new UsageError('--priority must be a positive whole-number position');
+    }
+    return priority;
+}
 function parseExplicitBoolean(value, name) {
     if (value !== 'true' && value !== 'false') {
         throw new UsageError(`${name} must be true or false`);
@@ -274,6 +284,31 @@ function parseInvestments(args, baseUrl) {
     }
     return withBaseUrl({ command: 'investments', ...(accountRef ? { accountRef } : {}) }, baseUrl);
 }
+function parseBudget(args, baseUrl) {
+    const update = args[0] === 'update';
+    if (update)
+        args.shift();
+    const { values, apply } = parseNamedOptions(args, update ? 'budget update' : 'budget', new Set(update ? ['--scope', '--period', '--input'] : ['--scope', '--period']));
+    if (!update && apply)
+        throw new UsageError('Unknown budget option: --apply');
+    const scope = requiredOption(values, '--scope', update ? 'budget update' : 'budget');
+    if (scope !== 'personal' && scope !== 'joint') {
+        throw new UsageError('--scope must be personal or joint');
+    }
+    const period = values.get('--period');
+    const common = {
+        scope: scope,
+        ...(period === undefined ? {} : { periodKey: parseGoalMonthKey(period, '--period') }),
+    };
+    if (!update)
+        return withBaseUrl({ command: 'budget', ...common }, baseUrl);
+    return withBaseUrl({
+        command: 'budget-update',
+        ...common,
+        input: requiredOption(values, '--input', 'budget update'),
+        apply,
+    }, baseUrl);
+}
 function parseCategories(args, baseUrl) {
     const subcommand = args.shift();
     if (subcommand === undefined || subcommand === 'list') {
@@ -442,6 +477,7 @@ function parseGoals(args, baseUrl) {
         let targetAmount;
         let targetMonthKey;
         let isAchieved;
+        let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
             const argument = args[index];
@@ -472,7 +508,8 @@ function parseGoals(args, baseUrl) {
                 && option !== '--name'
                 && option !== '--target-amount'
                 && option !== '--target-month'
-                && option !== '--achieved') {
+                && option !== '--achieved'
+                && option !== '--priority') {
                 throw new UsageError(`Unknown goals update option: ${argument}`);
             }
             const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
@@ -496,6 +533,9 @@ function parseGoals(args, baseUrl) {
                 }
                 targetMonthKey = parseGoalMonthKey(value, option);
             }
+            else if (option === '--priority') {
+                priority = setOnce(priority, parseGoalPriority(value), option);
+            }
             else {
                 isAchieved = setOnce(isAchieved, parseExplicitBoolean(value, option), option);
             }
@@ -505,9 +545,17 @@ function parseGoals(args, baseUrl) {
         if (name === undefined
             && targetAmount === undefined
             && targetMonthKey === undefined
-            && isAchieved === undefined) {
+            && isAchieved === undefined
+            && priority === undefined) {
             throw new UsageError('goals update requires at least one field to update');
         }
+        if (priority !== undefined
+            && (name !== undefined
+                || targetAmount !== undefined
+                || targetMonthKey !== undefined
+                || isAchieved !== undefined)) {
+            throw new UsageError('--priority must be used on its own');
+        }
         return withBaseUrl({
             command: 'goals-update',
             goalId,
@@ -515,6 +563,7 @@ function parseGoals(args, baseUrl) {
             ...(targetAmount === undefined ? {} : { targetAmount }),
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
             ...(isAchieved === undefined ? {} : { isAchieved }),
+            ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);
     }
@@ -599,6 +648,9 @@ function helpTopic(argv) {
             return 'line-items-rename';
         return undefined;
     }
+    if (command === 'budget') {
+        return subcommand === 'update' ? 'budget-update' : 'budget';
+    }
     if (command === 'accounts'
         || command === 'transactions'
         || command === 'assign'
@@ -640,6 +692,9 @@ export function parseArgs(argv) {
     if (command === 'investments') {
         return parseInvestments(args, baseUrl);
     }
+    if (command === 'budget') {
+        return parseBudget(args, baseUrl);
+    }
     if (command === 'transactions') {
         return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);
     }

package/dist/cli.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { ICON_KEYS } from './category-metadata.js';
-import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.6.0';
+export const CLI_VERSION = '0.8.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -28,6 +28,9 @@ export function usageText() {
         '  sloth-agent accounts [list] [--base-url URL]',
         '  sloth-agent accounts update --account-ref REF --goal-savings-source true|false [--apply]',
         '  sloth-agent investments [--account-ref REF] [--base-url URL]',
+        '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
+        '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
+        '    --input budget.json [--apply] [--base-url URL]',
         '  sloth-agent categories [list] [--base-url URL]',
         '  sloth-agent categories create --name NAME --icon-key KEY --type TYPE [--apply]',
         '  sloth-agent categories rename --category-id ID --name NAME [--apply]',
@@ -351,6 +354,70 @@ export function investmentsHelpText() {
         '  provider-native and are not converted or guaranteed to reconcile to totals.',
     ].join('\n');
 }
+export function budgetHelpText() {
+    return [
+        'Sloth Agent CLI — budget',
+        '',
+        'Read one personal or joint budget period.',
+        '',
+        'Usage:',
+        '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
+        '',
+        'Options:',
+        '  --scope personal|joint  Required. Budget ownership scope.',
+        '  --period YYYY-MM        Optional. Defaults to the current Sloth budget period.',
+        '  --base-url URL          Optional. Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access:',
+        '  This command is read-only and requires agent:read.',
+        '',
+        'Output:',
+        '  JSON containing scope, periodKey, periodStatus, currency, and effectiveFromPeriodKey.',
+        '  funding contains current stored to-assign and reserve amounts when that period exists.',
+        '  categories[].lineItems contains line-item IDs, names, and planned amounts in pence.',
+        '  Categories also include plannedPence and assignedPence.',
+    ].join('\n');
+}
+export function budgetUpdateHelpText() {
+    return [
+        'Sloth Agent CLI — budget update',
+        '',
+        'Preview or update planned line-item amounts for one budget scope.',
+        '',
+        'Usage:',
+        '  sloth-agent budget update --scope personal|joint [--period YYYY-MM] --input FILE [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --scope personal|joint  Budget ownership scope.',
+        '  --input FILE            JSON file containing allocations.',
+        '',
+        'Optional inputs:',
+        '  --period YYYY-MM        Defaults to the current Sloth budget period.',
+        '  --apply                 Send the update. Without it, only validate and preview.',
+        '  --base-url URL          Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Input format:',
+        '  {"allocations":[{"categoryId":"groceries","lineItemId":"weekly","plannedPence":45000}]}',
+        '  Provide 1 to 100 unique categoryId and lineItemId pairs.',
+        '  plannedPence must be a nonnegative whole number of pence.',
+        '',
+        'Write behavior:',
+        '  Without --apply, returns JSON after local validation and does not load credentials',
+        '  or contact Sloth Money. A successful preview does not guarantee the remote write.',
+        '  With --apply, each supplied amount patches a complete selected-period budget.',
+        '  The resulting complete budget overwrites the selected period and every explicit future plan.',
+        '  A later update from another period overwrites that period and everything after it.',
+        '  Historical periods cannot be changed. Applying requires agent:write.',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, endpoint, method, and the validated payload.',
+        '  Apply mode returns the complete persisted budget response.',
+    ].join('\n');
+}
 export function transactionsHelpText() {
     return [
         'Sloth Agent CLI — transactions',
@@ -495,7 +562,7 @@ export function goalsListHelpText() {
         '  This command is read-only.',
         '',
         'Output:',
-        '  JSON containing currency and goals. Each goal contains id, name,',
+        '  JSON containing currency and goals. Each goal contains id, name, priority,',
         '  targetAmount, targetMonthKey, isAchieved, and sharedWithPartner.',
     ].join('\n');
 }
@@ -548,6 +615,7 @@ export function goalsUpdateHelpText() {
         '  --target-month YYYY-MM       Optional. Replace the target month.',
         '  --clear-target-month         Optional. Remove the target month.',
         '  --achieved=true|false        Optional. Mark the goal achieved or active.',
+        '  --priority POSITION          Optional. Positive whole-number position; 1 is highest.',
         '  --apply                      Optional. Write the partial update.',
         '  --base-url URL               Optional. Override the API origin.',
         '  -h, --help                   Show this help.',
@@ -555,6 +623,11 @@ export function goalsUpdateHelpText() {
         '',
         'Constraints:',
         '  Provide at least one field to update.',
+        '  Priority must be updated on its own.',
+        '  Priority 1 is highest. The position cannot exceed the current goal count.',
+        '  Moving a goal shifts the intervening goals automatically.',
+        '  Forecast assignments and shared progress refresh when the owner next opens',
+        '  the Forecast screen.',
         '  Set and clear options for the same field are mutually exclusive.',
         '  Marking a goal achieved removes its forecast assignment.',
         '  Marking it active again does not restore the previous assignment.',
@@ -567,6 +640,9 @@ export function goalsUpdateHelpText() {
         '  Without --apply, the command returns a dry-run preview and does not write.',
         '  Applying requires a write-enabled token created with Allow changes.',
         '',
+        'Example:',
+        '  sloth-agent goals update --goal-id goal-3 --priority 2 --apply',
+        '',
         'Output:',
         '  Preview mode returns dryRun, method, endpoint, and payload.',
         '  Apply mode returns the complete persisted goal and currency.',
@@ -636,6 +712,8 @@ export function commandHelpText(topic) {
         accounts: accountsHelpText,
         'accounts-update': accountsUpdateHelpText,
         investments: investmentsHelpText,
+        budget: budgetHelpText,
+        'budget-update': budgetUpdateHelpText,
         categories: categoriesHelpText,
         'categories-create': categoriesCreateHelpText,
         'categories-rename': categoriesRenameHelpText,
@@ -655,6 +733,23 @@ export function commandHelpText(topic) {
 function writeJson(write, data) {
     write(`${JSON.stringify(data, null, 2)}\n`);
 }
+function withListedGoalPriorities(value) {
+    const response = value;
+    return {
+        ...response,
+        goals: response.goals.map((goal, index) => ({
+            ...goal,
+            priority: index + 1,
+        })),
+    };
+}
+function withUpdatedGoalPriority(value, priority) {
+    const response = value;
+    return {
+        ...response,
+        goal: { ...response.goal, priority },
+    };
+}
 function redact(value, token) {
     return token ? value.split(token).join('[REDACTED]') : value;
 }
@@ -721,6 +816,15 @@ function readAssignmentFile(filePath) {
         throw new UsageError(`Failed to read assignment JSON: ${message}`);
     }
 }
+function readBudgetFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Failed to read budget JSON: ${message}`);
+    }
+}
 function buildTransactionsQuery(filters) {
     const params = new URLSearchParams();
     if (filters.uncategorized !== undefined) {
@@ -898,6 +1002,22 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        const budgetUpdatePayload = parsed.command === 'budget-update'
+            ? validateBudgetUpdatePayload(readBudgetFile(parsed.input))
+            : undefined;
+        if (parsed.command === 'budget-update' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/budgets`,
+                method: 'PATCH',
+                payload: {
+                    scope: parsed.scope,
+                    ...(parsed.periodKey === undefined ? {} : { periodKey: parsed.periodKey }),
+                    ...budgetUpdatePayload,
+                },
+            });
+            return 0;
+        }
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
@@ -914,6 +1034,22 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'budget-update') {
+            const payload = {
+                scope: parsed.scope,
+                ...(parsed.periodKey === undefined ? {} : { periodKey: parsed.periodKey }),
+                ...budgetUpdatePayload,
+            };
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/budgets`, {
+                method: 'PATCH',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         if (parsed.command === 'categories-create'
             || parsed.command === 'categories-rename'
             || parsed.command === 'line-items-create'
@@ -994,6 +1130,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 ...(parsed.isAchieved === undefined
                     ? {}
                     : { isAchieved: parsed.isAchieved }),
+                ...(parsed.priority === undefined
+                    ? {}
+                    : { priority: parsed.priority }),
             };
             if (!parsed.apply) {
                 writeJson(writeStdout, {
@@ -1014,7 +1153,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse('goals-update', await parseHttpResponse(response, token));
-            writeJson(writeStdout, data);
+            writeJson(writeStdout, parsed.priority === undefined
+                ? data
+                : withUpdatedGoalPriority(data, parsed.priority));
             return 0;
         }
         if (parsed.command === 'goals-delete') {
@@ -1077,6 +1218,19 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse('goals-list', await parseHttpResponse(response, token));
+            writeJson(writeStdout, withListedGoalPriorities(data));
+            return 0;
+        }
+        if (parsed.command === 'budget') {
+            const query = new URLSearchParams({ scope: parsed.scope });
+            if (parsed.periodKey !== undefined)
+                query.set('periodKey', parsed.periodKey);
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/budgets?${query.toString()}`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('budget', await parseHttpResponse(response, token));
             writeJson(writeStdout, data);
             return 0;
         }

package/dist/contracts.js

@@ -109,6 +109,36 @@ export function validateAssignmentPayload(value) {
     }
     return { assignments: payload.assignments.map(validateAssignment) };
 }
+export function validateBudgetUpdatePayload(value) {
+    const payload = requireObject(value, 'budget update payload');
+    rejectUnknownFields(payload, new Set(['allocations']), 'budget update payload');
+    if (!Array.isArray(payload.allocations)) {
+        throw new UsageError('allocations array is required');
+    }
+    if (payload.allocations.length < 1 || payload.allocations.length > 100) {
+        throw new UsageError('allocations must contain between 1 and 100 items');
+    }
+    const seen = new Set();
+    const allocations = payload.allocations.map((value, index) => {
+        const label = `allocations[${index}]`;
+        const allocation = requireObject(value, label);
+        rejectUnknownFields(allocation, new Set(['categoryId', 'lineItemId', 'plannedPence']), label);
+        const categoryId = requireString(allocation.categoryId, `${label}.categoryId`);
+        const lineItemId = requireString(allocation.lineItemId, `${label}.lineItemId`);
+        if (typeof allocation.plannedPence !== 'number'
+            || !Number.isSafeInteger(allocation.plannedPence)
+            || allocation.plannedPence < 0) {
+            throw new UsageError(`${label}.plannedPence must be a nonnegative safe integer`);
+        }
+        const key = `${categoryId}\u0000${lineItemId}`;
+        if (seen.has(key)) {
+            throw new UsageError(`${label} duplicates a categoryId and lineItemId pair`);
+        }
+        seen.add(key);
+        return { categoryId, lineItemId, plannedPence: allocation.plannedPence };
+    });
+    return { allocations };
+}
 function isLineItemMap(value) {
     if (!isObject(value))
         return false;
@@ -285,6 +315,61 @@ function isGoal(value) {
 function isCurrency(value) {
     return typeof value === 'string' && /^[A-Z]{3}$/.test(value);
 }
+function isNonnegativeSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value);
+}
+function isBudgetLineItem(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['id', 'name', 'plannedPence'])
+        && typeof value.id === 'string'
+        && value.id.trim().length > 0
+        && typeof value.name === 'string'
+        && value.name.trim().length > 0
+        && isNonnegativeSafeInteger(value.plannedPence));
+}
+function isBudgetCategory(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['id', 'name', 'plannedPence', 'assignedPence', 'lineItems'])
+        && typeof value.id === 'string'
+        && value.id.trim().length > 0
+        && typeof value.name === 'string'
+        && value.name.trim().length > 0
+        && isNonnegativeSafeInteger(value.plannedPence)
+        && (value.assignedPence === null || isSafeInteger(value.assignedPence))
+        && Array.isArray(value.lineItems)
+        && value.lineItems.every(isBudgetLineItem));
+}
+function isBudgetResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, [
+            'scope',
+            'periodKey',
+            'periodStatus',
+            'currency',
+            'effectiveFromPeriodKey',
+            'funding',
+            'categories',
+        ])
+        && (value.scope === 'personal' || value.scope === 'joint')
+        && typeof value.periodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.periodKey)
+        && (value.periodStatus === 'historical'
+            || value.periodStatus === 'current'
+            || value.periodStatus === 'future')
+        && isCurrency(value.currency)
+        && typeof value.effectiveFromPeriodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
+        && (value.funding === null
+            || (isObject(value.funding)
+                && hasOnlyFields(value.funding, ['toAssignPence', 'nextPeriodReservePence'])
+                && isSafeInteger(value.funding.toAssignPence)
+                && isSafeInteger(value.funding.nextPeriodReservePence)))
+        && Array.isArray(value.categories)
+        && value.categories.every(isBudgetCategory));
+}
 function isNullableNonEmptyString(value) {
     return value === null || (typeof value === 'string'
         && value.length > 0
@@ -409,23 +494,25 @@ export function parseApiResponse(command, value) {
             ? isAccountMutationResponse(value)
             : command === 'investments'
                 ? isInvestmentsResponse(value)
-                : command === 'categories'
-                    ? isCategoryResponse(value)
-                    : command === 'categories-create' || command === 'categories-rename'
-                        ? isCategoryMutationResponse(value)
-                        : command === 'line-items-create' || command === 'line-items-rename'
-                            ? isLineItemMutationResponse(value)
-                            : command === 'transactions'
-                                ? isTransactionsResponse(value)
-                                : command === 'assign'
-                                    ? isAssignmentResponse(value)
-                                    : command === 'ask-partner'
-                                        ? isPartnerResponse(value)
-                                        : command === 'goals-list'
-                                            ? isGoalsResponse(value)
-                                            : command === 'goals-delete'
-                                                ? isGoalDeleteResponse(value)
-                                                : isGoalMutationResponse(value);
+                : command === 'budget' || command === 'budget-update'
+                    ? isBudgetResponse(value)
+                    : command === 'categories'
+                        ? isCategoryResponse(value)
+                        : command === 'categories-create' || command === 'categories-rename'
+                            ? isCategoryMutationResponse(value)
+                            : command === 'line-items-create' || command === 'line-items-rename'
+                                ? isLineItemMutationResponse(value)
+                                : command === 'transactions'
+                                    ? isTransactionsResponse(value)
+                                    : command === 'assign'
+                                        ? isAssignmentResponse(value)
+                                        : command === 'ask-partner'
+                                            ? isPartnerResponse(value)
+                                            : command === 'goals-list'
+                                                ? isGoalsResponse(value)
+                                                : command === 'goals-delete'
+                                                    ? isGoalDeleteResponse(value)
+                                                    : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {