@slothmoney/agent-cli 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.21.0 - 2026-08-28
+
+- Add `scenarios` commands to list, create, update, activate, and delete the
+  month-anchored choices used by Goal forecasts.
+- Preview every scenario change against Sloth's canonical planner with zero
+  writes; `--apply` remains the explicit write boundary.
+- Create the common No/Yes choice directly, support recurring and one-off
+  account contributions, and return the recalculated Goal roadmap.
+
 ## 0.20.0 - 2026-08-27
 
 - Add `portfolio` views for personal, partner-shared, and combined household

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect personal and household accounts, investments, and budgets, manage goals, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
+Use your own agent to inspect personal and household accounts, investments, and budgets, manage goals and forecast scenarios, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications 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.17.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.21.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`, `portfolio`,
-`budget`, `categories`, `transactions`, and `goals` list. Enable **Allow changes** when
+`budget`, `categories`, `transactions`, `goals`, and `scenarios` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
-or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
+or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals and scenarios. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -122,6 +122,9 @@ sloth-agent goals create --help
 sloth-agent goals update --help
 sloth-agent goals mark-spent --help
 sloth-agent goals restore --help
+sloth-agent scenarios create --help
+sloth-agent scenarios update --help
+sloth-agent scenarios activate --help
 sloth-agent ask-partner --help
 ```
 
@@ -748,6 +751,52 @@ one-based `priority`; `1` is highest. Moving one goal automatically shifts the
 goals between its old and new positions. Sloth recalculates the active-scenario
 roadmap before every applied Goal mutation and returns the updated forecast.
 
+List the scenarios that supply assumptions to that roadmap:
+
+```bash
+sloth-agent scenarios
+```
+
+Create a monthly contribution choice. Preview is the default and performs zero
+writes; add `--apply` after reviewing the returned scenario and recalculated
+Goals:
+
+```bash
+sloth-agent scenarios create \
+  --month 2026-09 \
+  --name "Deposit £100 into the shopping pot each month?" \
+  --account-ref sloth_account_v1_... \
+  --recurring-amount 100
+```
+
+Creation adds No and Yes options and activates Yes. The recurring contribution
+continues until a later active scenario changes it. A one-off amount applies
+only in the scenario month. Scenarios alter the forecast; they do not move
+money.
+
+Use stable IDs from `scenarios` output to edit or select an option:
+
+```bash
+sloth-agent scenarios update \
+  --month 2026-09 \
+  --option-id yes \
+  --account-ref sloth_account_v1_... \
+  --recurring-amount 125 \
+  --apply
+
+sloth-agent scenarios activate \
+  --month 2026-09 \
+  --option-id no \
+  --apply
+
+sloth-agent scenarios delete --month 2026-09 --apply
+```
+
+For recurring contributions, `--recurring-amount 0` explicitly stops the
+earlier amount. `--clear-recurring` removes this month's override, so the
+earlier recurring amount continues. Contribution updates use the active option
+when `--option-id` is omitted.
+
 Read uncategorised contributions to the joint budget:
 
 ```bash

package/dist/args.js

@@ -67,6 +67,16 @@ function parsePositiveDecimalAmount(value, name) {
     }
     return amount;
 }
+function parseNonNegativeDecimalAmount(value, name) {
+    if (!/^\d+(?:\.\d{1,2})?$/.test(value)) {
+        throw new UsageError(`${name} must be zero or a positive amount with at most two decimal places`);
+    }
+    const amount = Number(value);
+    if (!Number.isFinite(amount) || amount < 0) {
+        throw new UsageError(`${name} must be zero or a positive amount with at most two decimal places`);
+    }
+    return amount;
+}
 function parsePositiveAmountPence(value, name) {
     validatePositiveDecimalAmount(value, name);
     const [wholePounds, fractionalPounds = ''] = value.split('.');
@@ -864,6 +874,226 @@ function parseGoals(args, baseUrl) {
     }
     throw new UsageError(`Unknown goals command: ${subcommand}`);
 }
+function parseScenarioText(value, option, maxLength = 60) {
+    const text = value.trim();
+    if (text.length > maxLength) {
+        throw new UsageError(`${option} must be at most ${maxLength} characters`);
+    }
+    return text;
+}
+function parseScenarios(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown scenarios list option: ${args[0]}`);
+        }
+        return withBaseUrl({ command: 'scenarios-list' }, baseUrl);
+    }
+    if (subcommand === 'create') {
+        let monthKey;
+        let name;
+        let accountRef;
+        let recurringAmount;
+        let oneOffAmount;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month'
+                && option !== '--name'
+                && option !== '--account-ref'
+                && option !== '--recurring-amount'
+                && option !== '--one-off-amount') {
+                throw new UsageError(`Unknown scenarios create option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else if (option === '--name') {
+                name = setOnce(name, parseScenarioText(value, option), option);
+            }
+            else if (option === '--account-ref') {
+                accountRef = setOnce(accountRef, parseAccountRef(value), option);
+            }
+            else if (option === '--recurring-amount') {
+                recurringAmount = setOnce(recurringAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+            else {
+                oneOffAmount = setOnce(oneOffAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError('scenarios create requires --month <YYYY-MM>');
+        if (!name)
+            throw new UsageError('scenarios create requires --name <name>');
+        if (!accountRef)
+            throw new UsageError('scenarios create requires --account-ref <accountRef>');
+        if (recurringAmount === undefined && oneOffAmount === undefined) {
+            throw new UsageError('scenarios create requires --recurring-amount or --one-off-amount');
+        }
+        if ((recurringAmount ?? 0) === 0 && (oneOffAmount ?? 0) === 0) {
+            throw new UsageError('scenarios create requires at least one positive contribution');
+        }
+        return withBaseUrl({
+            command: 'scenarios-create',
+            monthKey,
+            name,
+            accountRef,
+            ...(recurringAmount === undefined ? {} : { recurringAmount }),
+            ...(oneOffAmount === undefined
+                ? recurringAmount === undefined ? {} : { oneOffAmount: 0 }
+                : { oneOffAmount }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'update') {
+        let monthKey;
+        let name;
+        let optionId;
+        let optionLabel;
+        let accountRef;
+        let recurringAmount;
+        let oneOffAmount;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            if (argument === '--clear-recurring') {
+                if (recurringAmount !== undefined) {
+                    throw new UsageError('--recurring-amount and --clear-recurring are mutually exclusive');
+                }
+                recurringAmount = null;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month'
+                && option !== '--name'
+                && option !== '--option-id'
+                && option !== '--option-label'
+                && option !== '--account-ref'
+                && option !== '--recurring-amount'
+                && option !== '--one-off-amount') {
+                throw new UsageError(`Unknown scenarios update option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else if (option === '--name') {
+                name = setOnce(name, parseScenarioText(value, option), option);
+            }
+            else if (option === '--option-id') {
+                optionId = setOnce(optionId, parseScenarioText(value, option, 200), option);
+            }
+            else if (option === '--option-label') {
+                optionLabel = setOnce(optionLabel, parseScenarioText(value, option), option);
+            }
+            else if (option === '--account-ref') {
+                accountRef = setOnce(accountRef, parseAccountRef(value), option);
+            }
+            else if (option === '--recurring-amount') {
+                if (recurringAmount !== undefined) {
+                    throw new UsageError('--recurring-amount and --clear-recurring are mutually exclusive');
+                }
+                recurringAmount = parseNonNegativeDecimalAmount(value, option);
+            }
+            else {
+                oneOffAmount = setOnce(oneOffAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError('scenarios update requires --month <YYYY-MM>');
+        if (optionLabel !== undefined && optionId === undefined) {
+            throw new UsageError('--option-label requires --option-id');
+        }
+        if ((recurringAmount !== undefined || oneOffAmount !== undefined) && !accountRef) {
+            throw new UsageError('scenario contribution changes require --account-ref');
+        }
+        if (accountRef !== undefined
+            && recurringAmount === undefined
+            && oneOffAmount === undefined) {
+            throw new UsageError('--account-ref requires a contribution change');
+        }
+        if (name === undefined
+            && optionLabel === undefined
+            && accountRef === undefined
+            && recurringAmount === undefined
+            && oneOffAmount === undefined) {
+            throw new UsageError('scenarios update requires at least one field to update');
+        }
+        return withBaseUrl({
+            command: 'scenarios-update',
+            monthKey,
+            ...(name === undefined ? {} : { name }),
+            ...(optionId === undefined ? {} : { optionId }),
+            ...(optionLabel === undefined ? {} : { optionLabel }),
+            ...(accountRef === undefined ? {} : { accountRef }),
+            ...(recurringAmount === undefined ? {} : { recurringAmount }),
+            ...(oneOffAmount === undefined ? {} : { oneOffAmount }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'activate' || subcommand === 'delete') {
+        let monthKey;
+        let optionId;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month' && !(subcommand === 'activate' && option === '--option-id')) {
+                throw new UsageError(`Unknown scenarios ${subcommand} option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else {
+                optionId = setOnce(optionId, parseScenarioText(value, option, 200), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError(`scenarios ${subcommand} requires --month <YYYY-MM>`);
+        if (subcommand === 'activate') {
+            if (!optionId)
+                throw new UsageError('scenarios activate requires --option-id <id>');
+            return withBaseUrl({
+                command: 'scenarios-activate', monthKey, optionId, apply,
+            }, baseUrl);
+        }
+        return withBaseUrl({ command: 'scenarios-delete', monthKey, apply }, baseUrl);
+    }
+    throw new UsageError(`Unknown scenarios command: ${subcommand}`);
+}
 function parseRules(args, baseUrl) {
     const subcommand = args.shift();
     if (subcommand === undefined || subcommand === 'list') {
@@ -945,6 +1175,19 @@ function helpTopic(argv) {
             return 'goals-delete';
         return 'goals';
     }
+    if (command === 'scenarios') {
+        if (subcommand === 'list')
+            return 'scenarios-list';
+        if (subcommand === 'create')
+            return 'scenarios-create';
+        if (subcommand === 'update')
+            return 'scenarios-update';
+        if (subcommand === 'activate')
+            return 'scenarios-activate';
+        if (subcommand === 'delete')
+            return 'scenarios-delete';
+        return 'scenarios';
+    }
     if (command === 'rules') {
         if (subcommand === 'get')
             return 'rules-get';
@@ -1021,6 +1264,9 @@ export function parseArgs(argv) {
     if (command === 'goals') {
         return parseGoals(args, baseUrl);
     }
+    if (command === 'scenarios') {
+        return parseScenarios(args, baseUrl);
+    }
     if (command === 'rules') {
         return parseRules(args, baseUrl);
     }

package/dist/cli.js

@@ -6,7 +6,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, parseAssignmentOperationResponse, toLegacyAssignmentResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.20.0';
+export const CLI_VERSION = '0.21.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -68,6 +68,12 @@ export function usageText() {
         '  sloth-agent goals mark-spent --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent goals restore --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent goals delete --goal-id ID [--apply] [--base-url URL]',
+        '  sloth-agent scenarios [list] [--base-url URL]',
+        '  sloth-agent scenarios create --month YYYY-MM --name NAME --account-ref REF',
+        '    [--recurring-amount AMOUNT] [--one-off-amount AMOUNT] [--apply]',
+        '  sloth-agent scenarios update --month YYYY-MM [fields] [--apply]',
+        '  sloth-agent scenarios activate --month YYYY-MM --option-id ID [--apply]',
+        '  sloth-agent scenarios delete --month YYYY-MM [--apply]',
         '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
         '',
         'Help:',
@@ -958,6 +964,192 @@ export function goalsDeleteHelpText() {
         '  Apply mode returns deleted and deletedGoalId.',
     ].join('\n');
 }
+export function scenariosHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios',
+        '',
+        'Manage the month-anchored choices used by the Goal forecast.',
+        'Each scenario contains options. Its active option controls the forecast calculation.',
+        '',
+        'Commands:',
+        '  sloth-agent scenarios list       List scenarios and their options.',
+        '  sloth-agent scenarios create     Create a No/Yes scenario.',
+        '  sloth-agent scenarios update     Change a scenario or option.',
+        '  sloth-agent scenarios activate   Make an option active.',
+        '  sloth-agent scenarios delete     Remove a scenario.',
+        '',
+        'Help:',
+        '  Run sloth-agent scenarios <command> --help for command-specific details.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function scenariosListHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios list',
+        '',
+        'List each scenario, its active option, and account contributions.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios [list] [--base-url URL] [-h]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Behavior:',
+        'This command is read-only and requires agent:read.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with currency, forecastBasis, and scenarios. Each scenario contains',
+        '  activeOptionId and options with isActive and account contributions.',
+    ].join('\n');
+}
+export function scenariosCreateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios create',
+        '',
+        'Create a month-anchored choice and recalculate the Goal roadmap.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios create --month YYYY-MM --name NAME --account-ref REF',
+        '    [--recurring-amount AMOUNT] [--one-off-amount AMOUNT] [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM              Month when this scenario begins.',
+        '  --name NAME                  Question shown for the scenario, up to 60 characters.',
+        '  --account-ref REF            Exact accountRef from sloth-agent accounts.',
+        '',
+        'Contribution: provide at least one:',
+        '  --recurring-amount AMOUNT    Optional monthly contribution in the budget currency.',
+        '  --one-off-amount AMOUNT      Optional contribution for this month.',
+        '  AMOUNT accepts zero or a positive decimal with at most two decimal places.',
+        '  At least one supplied amount must be positive.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the scenario; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Provide at least one positive contribution. A recurring contribution continues',
+        'until a later active scenario changes it. Creation adds No and Yes options and',
+        'activates Yes. It records a forecast assumption and does not move money.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth authenticates, calculates the result, and performs zero writes.',
+        '  With --apply, Sloth saves the scenario using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the proposed or saved scenario, and',
+        '  recalculated Goals. Preview and apply use the same output contract.',
+        '',
+        'Example:',
+        '  sloth-agent scenarios create --month 2026-09 \\',
+        '    --name "Deposit £100 into the shopping pot each month?" \\',
+        '    --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --recurring-amount 100',
+    ].join('\n');
+}
+export function scenariosUpdateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios update',
+        '',
+        'Change a scenario, one option, or an account contribution.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios update --month YYYY-MM [fields] [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM                 Scenario month.',
+        '',
+        'Fields:',
+        '  --name NAME                     Rename the scenario, up to 60 characters.',
+        '  --option-id ID                  Select an option ID, up to 200 characters.',
+        '  --option-label LABEL            Rename it, up to 60 characters; requires --option-id.',
+        '  --account-ref REF               Account for contribution changes.',
+        '  --recurring-amount AMOUNT       Set a monthly contribution; cannot be used',
+        '                                  with --clear-recurring.',
+        '  --clear-recurring               Inherit the earlier recurring amount.',
+        '  --one-off-amount AMOUNT         Set this month\'s one-off contribution.',
+        '  Amounts accept zero or a positive decimal with at most two decimal places.',
+        '  Contribution fields require --account-ref, and --account-ref requires one',
+        '  of those fields. Provide at least one field that changes the scenario.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the change; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Contribution changes use the active option when --option-id is omitted.',
+        'For recurring contributions, zero explicitly stops the earlier recurring amount.',
+        '--clear-recurring removes this override so the earlier recurring amount continues.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth authenticates, calculates the result, and performs zero writes.',
+        '  With --apply, Sloth saves the change using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the proposed or saved scenario, and',
+        '  recalculated Goals. Preview and apply use the same output contract.',
+    ].join('\n');
+}
+export function scenariosActivateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios activate',
+        '',
+        'Select the option that controls the forecast and recalculates Goals.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios activate --month YYYY-MM --option-id ID [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM   Scenario month.',
+        '  --option-id ID    Exact option ID from scenarios list, up to 200 characters.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the active option; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Write behavior:',
+        'Without --apply, Sloth calculates the result and performs zero writes.',
+        'With --apply, Sloth saves the active option using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the selected scenario, and recalculated Goals.',
+    ].join('\n');
+}
+export function scenariosDeleteHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios delete',
+        '',
+        'Remove one scenario. Sloth recalculates Goals without it.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios delete --month YYYY-MM [--apply] [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM   Scenario month.',
+        '',
+        'Options:',
+        '  --apply          Optional. Remove the scenario; otherwise preview deletion.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Write behavior:',
+        'Without --apply, Sloth calculates the result and performs zero writes.',
+        'With --apply, Sloth removes the scenario using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, deletedMonthKey, and recalculated Goals.',
+    ].join('\n');
+}
 export function askPartnerHelpText() {
     return [
         'Sloth Agent CLI — ask-partner',
@@ -1234,6 +1426,12 @@ export function commandHelpText(topic) {
         'goals-mark-spent': goalsMarkSpentHelpText,
         'goals-restore': goalsRestoreHelpText,
         'goals-delete': goalsDeleteHelpText,
+        scenarios: scenariosHelpText,
+        'scenarios-list': scenariosListHelpText,
+        'scenarios-create': scenariosCreateHelpText,
+        'scenarios-update': scenariosUpdateHelpText,
+        'scenarios-activate': scenariosActivateHelpText,
+        'scenarios-delete': scenariosDeleteHelpText,
         'ask-partner': askPartnerHelpText,
     };
     return helpByTopic[topic]();
@@ -1556,6 +1754,77 @@ function hasFailures(value) {
         return false;
     return Array.isArray(value.failed) && value.failed.length > 0;
 }
+function scenarioRequestDescriptor(parsed, baseUrl) {
+    const previewEndpoint = `${baseUrl}/api/agent/v1/scenarios/preview`;
+    switch (parsed.command) {
+        case 'scenarios-create': {
+            const scenario = {
+                monthKey: parsed.monthKey,
+                name: parsed.name,
+                accountRef: parsed.accountRef,
+                ...(parsed.recurringAmount === undefined
+                    ? {}
+                    : { recurringAmount: parsed.recurringAmount }),
+                ...(parsed.oneOffAmount === undefined
+                    ? {}
+                    : { oneOffAmount: parsed.oneOffAmount }),
+            };
+            return parsed.apply
+                ? { endpoint: `${baseUrl}/api/agent/v1/scenarios`, method: 'POST', body: scenario }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'create', scenario },
+                };
+        }
+        case 'scenarios-update': {
+            const updates = {
+                ...(parsed.name === undefined ? {} : { name: parsed.name }),
+                ...(parsed.optionId === undefined ? {} : { optionId: parsed.optionId }),
+                ...(parsed.optionLabel === undefined ? {} : { optionLabel: parsed.optionLabel }),
+                ...(parsed.accountRef === undefined ? {} : { accountRef: parsed.accountRef }),
+                ...(parsed.recurringAmount === undefined
+                    ? {}
+                    : { recurringAmount: parsed.recurringAmount }),
+                ...(parsed.oneOffAmount === undefined ? {} : { oneOffAmount: parsed.oneOffAmount }),
+            };
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}`,
+                    method: 'PATCH',
+                    body: updates,
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'update', monthKey: parsed.monthKey, updates },
+                };
+        }
+        case 'scenarios-activate':
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}/activate`,
+                    method: 'POST',
+                    body: { optionId: parsed.optionId },
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'activate', monthKey: parsed.monthKey, optionId: parsed.optionId },
+                };
+        case 'scenarios-delete':
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}`,
+                    method: 'DELETE',
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'delete', monthKey: parsed.monthKey },
+                };
+    }
+}
 export async function runCli(argv = process.argv.slice(2), options = {}) {
     const environment = options.env ?? process.env;
     const fetchImplementation = options.fetch ?? globalThis.fetch;
@@ -2001,6 +2270,31 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'scenarios-list') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/scenarios`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('scenarios-list', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'scenarios-create'
+            || parsed.command === 'scenarios-update'
+            || parsed.command === 'scenarios-activate'
+            || parsed.command === 'scenarios-delete') {
+            const request = scenarioRequestDescriptor(parsed, baseUrl);
+            const response = await fetchImplementation(request.endpoint, {
+                method: request.method,
+                headers: request.body === undefined
+                    ? headers
+                    : { ...headers, 'Content-Type': 'application/json' },
+                ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('scenarios-mutation', await parseHttpResponse(response, token)));
+            return 0;
+        }
         if (parsed.command === 'assign') {
             const payload = assignmentPayload;
             const data = await applyAssignments(fetchImplementation, sleep, baseUrl, token, payload);

package/dist/contracts.js

@@ -1054,6 +1054,101 @@ function isGoalDeleteResponse(value) {
         && typeof value.deletedGoalId === 'string'
         && value.deletedGoalId.trim().length > 0);
 }
+function isScenarioAmount(value) {
+    return typeof value === 'number'
+        && Number.isFinite(value)
+        && value >= 0
+        && Math.abs(value * 100 - Math.round(value * 100)) < Number.EPSILON * 100;
+}
+function isScenarioContribution(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'accountRef',
+            'accountLabel',
+            'accountType',
+            'recurringAmount',
+            'oneOffAmount',
+        ])
+        && isAccountRef(value.accountRef)
+        && typeof value.accountLabel === 'string'
+        && value.accountLabel.trim().length > 0
+        && (value.accountType === 'current'
+            || value.accountType === 'savings'
+            || value.accountType === 'investments')
+        && (value.recurringAmount === null
+            || isScenarioAmount(value.recurringAmount))
+        && isScenarioAmount(value.oneOffAmount);
+}
+function isScenarioOption(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['id', 'label', 'isActive', 'contributions'])
+        && typeof value.id === 'string'
+        && value.id.trim().length > 0
+        && value.id === value.id.trim()
+        && value.id.length <= 200
+        && typeof value.label === 'string'
+        && value.label.trim().length > 0
+        && value.label === value.label.trim()
+        && value.label.length <= 60
+        && typeof value.isActive === 'boolean'
+        && Array.isArray(value.contributions)
+        && value.contributions.every(isScenarioContribution);
+}
+function hasConsistentScenarioOptions(options, activeOptionId) {
+    const parsedOptions = options.filter(isObject);
+    if (parsedOptions.length !== options.length)
+        return false;
+    const optionIds = parsedOptions.map(option => String(option.id));
+    const activeOptions = parsedOptions.filter(option => option.isActive === true);
+    return new Set(optionIds).size === optionIds.length
+        && activeOptions.length === 1
+        && activeOptions[0]?.id === activeOptionId;
+}
+function isScenario(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['monthKey', 'name', 'activeOptionId', 'options'])
+        && isMonthKeyOrNull(value.monthKey)
+        && value.monthKey !== null
+        && (value.name === null
+            || (typeof value.name === 'string'
+                && value.name.trim().length > 0
+                && value.name === value.name.trim()
+                && value.name.length <= 60))
+        && typeof value.activeOptionId === 'string'
+        && value.activeOptionId.trim().length > 0
+        && value.activeOptionId === value.activeOptionId.trim()
+        && value.activeOptionId.length <= 200
+        && Array.isArray(value.options)
+        && value.options.length > 0
+        && value.options.every(isScenarioOption)
+        && hasConsistentScenarioOptions(value.options, value.activeOptionId);
+}
+function isScenariosResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'scenarios'])
+        && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
+        && Array.isArray(value.scenarios)
+        && value.scenarios.every(isScenario);
+}
+function isScenarioMutationResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'currency',
+            'changed',
+            'forecastBasis',
+            'scenario',
+            'deletedMonthKey',
+            'goals',
+        ])
+        && isCurrency(value.currency)
+        && typeof value.changed === 'boolean'
+        && isForecastBasis(value.forecastBasis)
+        && (value.scenario === null || isScenario(value.scenario))
+        && isMonthKeyOrNull(value.deletedMonthKey)
+        && Array.isArray(value.goals)
+        && value.goals.every(isGoal);
+}
 function isReceiptConfirmation(value) {
     try {
         validateReceiptConfirmation(value);
@@ -1150,11 +1245,15 @@ export function parseApiResponse(command, value) {
                                                                                             ? isPartnerResponse(value)
                                                                                             : command === 'goals-list'
                                                                                                 ? isGoalsResponse(value)
-                                                                                                : command === 'goals-preview'
-                                                                                                    ? isGoalPreviewResponse(value)
-                                                                                                    : command === 'goals-delete'
-                                                                                                        ? isGoalDeleteResponse(value)
-                                                                                                        : isGoalMutationResponse(value);
+                                                                                                : command === 'scenarios-list'
+                                                                                                    ? isScenariosResponse(value)
+                                                                                                    : command === 'scenarios-mutation'
+                                                                                                        ? isScenarioMutationResponse(value)
+                                                                                                        : command === 'goals-preview'
+                                                                                                            ? isGoalPreviewResponse(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.20.0",
+  "version": "0.21.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {