@slothmoney/agent-cli 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.20.0 - 2026-08-27
+
+- Add `portfolio` views for personal, partner-shared, and combined household
+  savings and investments.
+- Add account-level partner visibility updates for private, balance-only, and
+  balance-and-holdings sharing.
+- Keep portfolio results strict, machine-readable, and explicit about refresh
+  status and excluded currencies.
+
+## 0.19.0 - 2026-08-26
+
+- Make every Goal use one explicit personal Goal-funding account and expose
+  the calculated `forecastMonthKey`, effective priority, account details, and
+  `forecastBasis` in Goal results.
+- Make `goals create` preview against Sloth's active scenario on the server;
+  preview performs no writes and `--apply` remains the write boundary.
+- Add `--account-ref` and `--priority` to Goal creation, allow account
+  reassignment during Goal updates, and rename account eligibility to
+  `isGoalFundingAccount` / `--goal-funding-account`.
+- Surface corrective API error codes without adding affordability judgments or
+  desired-date comparisons to the CLI.
+
 ## 0.18.1 - 2026-08-25
 
 - Require the deployed historical-activity response for `budget status` and

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect 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, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -24,7 +24,7 @@ Create a personal access token in Sloth Money under
 **Settings > Developer access**, then choose the authentication method for
 where the CLI runs.
 
-New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`,
+New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`, `portfolio`,
 `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, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
@@ -103,6 +103,7 @@ options, output, and examples. For example:
 ```bash
 sloth-agent auth login --help
 sloth-agent accounts --help
+sloth-agent portfolio --help
 sloth-agent budget --help
 sloth-agent budget status --help
 sloth-agent budget update --help
@@ -584,7 +585,8 @@ sloth-agent accounts
 The command is read-only and cache-only: it does not refresh linked banks or
 change account data. Each result contains an opaque `accountRef`, personal or
 joint ownership, connected or manual source, native balance/currency when
-known, `lastBalanceUpdatedAt`, `connectionState`, and `isGoalSavingsSource`.
+known, `lastBalanceUpdatedAt`, `connectionState`, `isGoalFundingAccount`, and
+`partnerVisibility`.
 Missing values are JSON
 `null`; currencies are never converted or combined. Partner personal accounts
 are excluded, while enabled shared joint accounts follow Sloth's existing
@@ -604,9 +606,9 @@ Copy the value from `sloth-agent accounts`. Account references are the public
 account identifier for transaction filtering.
 
 Account changes are previews unless `--apply` is present. Connected accounts
-support only goal-savings membership. Manual current accounts support their
+support Goal-funding eligibility and partner visibility. Manual current accounts support their
 institution, name, currency, and ownership. Manual balance accounts also
-support balance, Savings/Investments type, and goal-savings membership.
+support balance, Savings/Investments type, and Goal-funding eligibility.
 Partner-owned shared accounts return an explanatory error.
 
 ```bash
@@ -618,14 +620,31 @@ sloth-agent accounts update \
   --ownership individual \
   --balance-amount 12500.75 \
   --account-type investments \
-  --goal-savings-source false
+  --goal-funding-account false \
+  --partner-visibility holdings
 
 sloth-agent accounts update \
   --account-ref sloth_account_v1_... \
-  --goal-savings-source false \
+  --partner-visibility balance \
   --apply
 ```
 
+Read the same current position from your, your partner's, or the combined
+household perspective:
+
+```bash
+sloth-agent portfolio
+sloth-agent portfolio --view partner
+sloth-agent portfolio --view household
+```
+
+The command waits up to 45 seconds for eligible linked balances to refresh,
+then returns cached data if work continues. Partner accounts appear only when
+their owner has shared the balance or linked holdings. Sharing is for household
+planning only. It does not change account ownership, transaction access, Goal
+funding, or who can move money. Totals use the viewer's budget currency and
+exclude other native currencies without converting them.
+
 Archive an owned manual account. The account disappears from active Sloth
 surfaces, but its underlying records are retained. Repeating an applied removal
 is safe and returns `changed: false`.
@@ -664,16 +683,24 @@ Goal writes are previews unless `--apply` is present:
 sloth-agent goals create \
   --name "Emergency fund" \
   --target-amount 12000 \
-  --type keep
+  --type keep \
+  --account-ref sloth_account_v1_...
 
 sloth-agent goals create \
   --name "Wedding" \
   --target-amount 22000 \
   --target-month 2027-06 \
   --type spend \
+  --account-ref sloth_account_v1_... \
   --apply
 ```
 
+Without `--apply`, Goal creation authenticates and asks Sloth to calculate the
+Goal without writing it. Preview and apply use the same active-scenario planner
+and return `forecastMonthKey`, the effective priority, the funding account, and
+`forecastBasis`. A null forecast includes the final projected month. The CLI
+does not compare the desired and forecast dates or return affordability advice.
+
 Every goal is either Keep or Spend. A Keep goal continues reserving its funded
 money. A Spend goal reserves money until you explicitly mark it spent. Goal
 list, create, and update output includes lowercase `goalType` and nullable
@@ -687,6 +714,7 @@ move it in the priority order:
 sloth-agent goals update \
   --goal-id goal-id \
   --target-month 2027-12 \
+  --account-ref sloth_account_v1_... \
   --type spend \
   --apply
 
@@ -715,13 +743,10 @@ required recovery action. Restoring clears `spentAt` and returns the goal to
 allocation at its saved priority. 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. Goal list output includes a
+Goal sharing remains app-managed. 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. Forecast assignments and shared pot progress are browser-owned
-derived state and refresh when the owner next opens the Forecast screen.
+goals between its old and new positions. Sloth recalculates the active-scenario
+roadmap before every applied Goal mutation and returns the updated forecast.
 
 Read uncategorised contributions to the joint budget:
 

package/dist/args.js

@@ -389,7 +389,8 @@ function parseAccounts(args, baseUrl) {
             '--ownership',
             '--balance-amount',
             '--account-type',
-            '--goal-savings-source',
+            '--goal-funding-account',
+            '--partner-visibility',
         ]));
         const institutionName = values.get('--institution-name');
         const accountName = values.get('--account-name');
@@ -397,7 +398,8 @@ function parseAccounts(args, baseUrl) {
         const ownershipValue = values.get('--ownership');
         const balanceValue = values.get('--balance-amount');
         const accountTypeValue = values.get('--account-type');
-        const sourceValue = values.get('--goal-savings-source');
+        const sourceValue = values.get('--goal-funding-account');
+        const partnerVisibility = values.get('--partner-visibility');
         if (currencyValue !== undefined && !/^[A-Za-z]{3}$/.test(currencyValue)) {
             throw new UsageError('--currency must be a three-letter currency code');
         }
@@ -412,7 +414,13 @@ function parseAccounts(args, baseUrl) {
             throw new UsageError('--account-type must be savings or investments');
         }
         if (sourceValue !== undefined && sourceValue !== 'true' && sourceValue !== 'false') {
-            throw new UsageError('--goal-savings-source must be true or false');
+            throw new UsageError('--goal-funding-account must be true or false');
+        }
+        if (partnerVisibility !== undefined
+            && partnerVisibility !== 'private'
+            && partnerVisibility !== 'balance'
+            && partnerVisibility !== 'holdings') {
+            throw new UsageError('--partner-visibility must be private, balance, or holdings');
         }
         const update = {
             ...(institutionName === undefined
@@ -429,7 +437,10 @@ function parseAccounts(args, baseUrl) {
             ...(accountTypeValue === undefined
                 ? {}
                 : { accountType: accountTypeValue }),
-            ...(sourceValue === undefined ? {} : { isGoalSavingsSource: sourceValue === 'true' }),
+            ...(sourceValue === undefined ? {} : { isGoalFundingAccount: sourceValue === 'true' }),
+            ...(partnerVisibility === undefined ? {} : {
+                partnerVisibility: partnerVisibility,
+            }),
         };
         if (Object.keys(update).length === 0) {
             throw new UsageError('accounts update requires at least one field to update');
@@ -471,6 +482,16 @@ function parseInvestments(args, baseUrl) {
     }
     return withBaseUrl({ command: 'investments', ...(accountRef ? { accountRef } : {}) }, baseUrl);
 }
+function parsePortfolio(args, baseUrl) {
+    const { values, apply } = parseNamedOptions(args, 'portfolio', new Set(['--view']));
+    if (apply)
+        throw new UsageError('portfolio does not accept --apply');
+    const view = values.get('--view') ?? 'mine';
+    if (view !== 'mine' && view !== 'partner' && view !== 'household') {
+        throw new UsageError('--view must be mine, partner, or household');
+    }
+    return withBaseUrl({ command: 'portfolio', view }, baseUrl);
+}
 function parseBudget(args, baseUrl) {
     const subcommand = args[0] === 'status' || args[0] === 'update' || args[0] === 'move'
         ? args.shift()
@@ -652,6 +673,8 @@ function parseGoals(args, baseUrl) {
         let targetAmount;
         let targetMonthKey;
         let goalType;
+        let fundingAccountRef;
+        let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
             const argument = args[index];
@@ -667,7 +690,9 @@ function parseGoals(args, baseUrl) {
             if (option !== '--name'
                 && option !== '--target-amount'
                 && option !== '--target-month'
-                && option !== '--type') {
+                && option !== '--type'
+                && option !== '--account-ref'
+                && option !== '--priority') {
                 throw new UsageError(`Unknown goals create option: ${argument}`);
             }
             const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
@@ -682,9 +707,15 @@ function parseGoals(args, baseUrl) {
             else if (option === '--target-month') {
                 targetMonthKey = setOnce(targetMonthKey, parseGoalMonthKey(value, option), option);
             }
-            else {
+            else if (option === '--type') {
                 goalType = setOnce(goalType, parseGoalType(value), option);
             }
+            else if (option === '--account-ref') {
+                fundingAccountRef = setOnce(fundingAccountRef, parseAccountRef(value), option);
+            }
+            else {
+                priority = setOnce(priority, parseGoalPriority(value), option);
+            }
         }
         if (!name)
             throw new UsageError('goals create requires --name <name>');
@@ -694,12 +725,17 @@ function parseGoals(args, baseUrl) {
         if (goalType === undefined) {
             throw new UsageError('goals create requires --type <keep|spend>');
         }
+        if (fundingAccountRef === undefined) {
+            throw new UsageError('goals create requires --account-ref <accountRef>');
+        }
         return withBaseUrl({
             command: 'goals-create',
             name,
             targetAmount,
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
             goalType,
+            fundingAccountRef,
+            ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);
     }
@@ -709,6 +745,7 @@ function parseGoals(args, baseUrl) {
         let targetAmount;
         let targetMonthKey;
         let goalType;
+        let fundingAccountRef;
         let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
@@ -734,6 +771,7 @@ function parseGoals(args, baseUrl) {
                 && option !== '--target-amount'
                 && option !== '--target-month'
                 && option !== '--type'
+                && option !== '--account-ref'
                 && option !== '--priority') {
                 throw new UsageError(`Unknown goals update option: ${argument}`);
             }
@@ -758,6 +796,9 @@ function parseGoals(args, baseUrl) {
             else if (option === '--priority') {
                 priority = setOnce(priority, parseGoalPriority(value), option);
             }
+            else if (option === '--account-ref') {
+                fundingAccountRef = setOnce(fundingAccountRef, parseAccountRef(value), option);
+            }
             else {
                 goalType = setOnce(goalType, parseGoalType(value), option);
             }
@@ -768,16 +809,10 @@ function parseGoals(args, baseUrl) {
             && targetAmount === undefined
             && targetMonthKey === undefined
             && goalType === undefined
+            && fundingAccountRef === undefined
             && priority === undefined) {
             throw new UsageError('goals update requires at least one field to update');
         }
-        if (priority !== undefined
-            && (name !== undefined
-                || targetAmount !== undefined
-                || targetMonthKey !== undefined
-                || goalType !== undefined)) {
-            throw new UsageError('--priority must be used on its own');
-        }
         return withBaseUrl({
             command: 'goals-update',
             goalId,
@@ -785,6 +820,7 @@ function parseGoals(args, baseUrl) {
             ...(targetAmount === undefined ? {} : { targetAmount }),
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
             ...(goalType === undefined ? {} : { goalType }),
+            ...(fundingAccountRef === undefined ? {} : { fundingAccountRef }),
             ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);
@@ -964,8 +1000,8 @@ function helpTopic(argv) {
             return 'accounts-remove';
         return command;
     }
-    if (command === 'investments')
-        return 'investments';
+    if (command === 'investments' || command === 'portfolio')
+        return command;
     return undefined;
 }
 export function parseArgs(argv) {
@@ -1000,6 +1036,9 @@ export function parseArgs(argv) {
     if (command === 'investments') {
         return parseInvestments(args, baseUrl);
     }
+    if (command === 'portfolio') {
+        return parsePortfolio(args, baseUrl);
+    }
     if (command === 'budget') {
         return parseBudget(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.18.1';
+export const CLI_VERSION = '0.20.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -34,6 +34,7 @@ export function usageText() {
         '  sloth-agent accounts update --account-ref REF [fields] [--apply]',
         '  sloth-agent accounts remove --account-ref REF [--apply]',
         '  sloth-agent investments [--account-ref REF] [--base-url URL]',
+        '  sloth-agent portfolio [--view mine|partner|household] [--base-url URL]',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '  sloth-agent budget status --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
@@ -61,7 +62,8 @@ export function usageText() {
         '  sloth-agent receipts remove --transaction-ref REF --revision N [--apply]',
         '  sloth-agent goals [list] [--base-url URL]',
         '  sloth-agent goals create --name NAME --target-amount AMOUNT',
-        '    --type keep|spend [--target-month YYYY-MM] [--apply] [--base-url URL]',
+        '    --type keep|spend --account-ref REF [--target-month YYYY-MM]',
+        '    [--priority POSITION] [--apply] [--base-url URL]',
         '  sloth-agent goals update --goal-id ID [fields] [--apply] [--base-url URL]',
         '  sloth-agent goals mark-spent --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent goals restore --goal-id ID [--apply] [--base-url URL]',
@@ -354,7 +356,7 @@ export function accountsHelpText() {
         '  accounts[].ownership   personal or joint',
         '  accounts[].balanceAmount and currency in the native currency when known',
         '  accounts[].connectionState and lastBalanceUpdatedAt for freshness',
-        '  accounts[].isGoalSavingsSource whether the owner uses it for goal savings',
+        '  accounts[].isGoalFundingAccount whether Goals may use the account',
     ].join('\n');
 }
 export function accountsUpdateHelpText() {
@@ -376,13 +378,16 @@ export function accountsUpdateHelpText() {
         '  --ownership individual|joint       Manual account ownership.',
         '  --balance-amount AMOUNT             Balance-only account balance.',
         '  --account-type savings|investments Balance-only account type.',
-        '  --goal-savings-source true|false   Goal-savings membership.',
+        '  --goal-funding-account true|false   Whether Goals may use this account.',
+        '  --partner-visibility private|balance|holdings',
+        '                                      What this account shares with your partner.',
         '',
         'Write behavior:',
         '  Without --apply, returns a JSON preview without credentials or a network request.',
         '  With --apply, requires agent:write on a write-enabled token and updates saved Sloth metadata.',
-        '  Connected accounts support only --goal-savings-source.',
-        '  Manual current accounts cannot change type, balance, or goal-savings membership.',
+        '  Connected accounts support --goal-funding-account and --partner-visibility.',
+        '  Sharing exposes planning data only. It does not change ownership or assign the account to Goals.',
+        '  Manual current accounts cannot change type, balance, or Goal-funding membership.',
         '  Partner-owned shared accounts cannot be changed.',
         '  Unknown, disconnected, or inaccessible references return Account not found.',
         ...API_ORIGIN_HELP_LINES,
@@ -441,6 +446,33 @@ export function investmentsHelpText() {
         '  provider-native and are not converted or guaranteed to reconcile to totals.',
     ].join('\n');
 }
+export function portfolioHelpText() {
+    return [
+        'Sloth Agent CLI — portfolio',
+        '',
+        'Read your savings and investments from one household planning perspective.',
+        '',
+        'Usage:',
+        '  sloth-agent portfolio [--view mine|partner|household] [--base-url URL]',
+        '',
+        'Options:',
+        '  --view mine|partner|household  Optional. Defaults to mine.',
+        '  --base-url URL                 Optional. Override the API origin.',
+        '  -h, --help                     Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access:',
+        '  This read-only command waits up to 45 seconds for eligible linked balances to refresh.',
+        '  Partner shows only balances or holdings your partner explicitly shared.',
+        '  Household combines your accounts with those shared balances and deduplicates joint accounts.',
+        '  Shared data supports planning only. It does not assign partner accounts to Goals or change ownership.',
+        '',
+        'Output:',
+        '  totals gives savings, investments, and tracked amounts in the viewer currency.',
+        '  accounts includes ownerRole, freshness, sharing level, and permitted holdings.',
+        '  refresh reports whether eligible linked balances refreshed or cached data was returned.',
+    ].join('\n');
+}
 export function budgetHelpText() {
     return [
         'Sloth Agent CLI — budget',
@@ -720,7 +752,7 @@ export function goalsHelpText() {
     return [
         'Sloth Agent CLI — goals',
         '',
-        'List, create, update, mark spent, restore, or delete your savings goals.',
+        'List, preview, create, update, mark spent, restore, or delete account-funded Goals.',
         '',
         'Commands:',
         '  sloth-agent goals list      List goals; "sloth-agent goals" is equivalent.',
@@ -754,9 +786,9 @@ export function goalsListHelpText() {
         '  This command is read-only.',
         '',
         'Output:',
-        '  JSON containing currency and goals. Each goal contains id, name, priority,',
-        '  targetAmount, targetMonthKey, goalType, nullable spentAt, and',
-        '  sharedWithPartner.',
+        '  JSON containing currency, forecastBasis, and goals. Each goal includes its',
+        '  effectivePriority, funding account, desired targetMonthKey, and calculated',
+        '  forecastMonthKey.',
     ].join('\n');
 }
 export function goalsCreateHelpText() {
@@ -766,30 +798,33 @@ export function goalsCreateHelpText() {
         'Preview or create a goal.',
         '',
         'Usage:',
-        '  sloth-agent goals create --name NAME --target-amount AMOUNT --type keep|spend [options]',
+        '  sloth-agent goals create --name NAME --target-amount AMOUNT --type keep|spend --account-ref REF [options]',
         '',
         'Options:',
         '  --name NAME                 Required. Goal name, 1 to 200 characters.',
         '  --target-amount AMOUNT      Required. Positive major-unit amount with up to 2 decimals.',
         '  --type keep|spend           Required. Keep reserves funded money; Spend is spent later.',
-        '  --target-month YYYY-MM      Optional. Target calendar month.',
+        '  --account-ref REF           Required. Personal Goal-funding account from accounts list.',
+        '  --target-month YYYY-MM      Optional. Desired calendar month; it does not change the forecast.',
+        '  --priority POSITION         Optional. One-based priority; defaults to append.',
         '  --apply                     Optional. Create the goal in Sloth Money.',
         '  --base-url URL              Optional. Override the API origin.',
         '  -h, --help                  Show this help.',
         ...API_ORIGIN_HELP_LINES,
         '',
         'Safety:',
-        '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Without --apply, the command authenticates and asks Sloth to calculate the Goal.',
+        '  The server performs no writes for a preview.',
         '  Applying requires a write-enabled token created with Allow changes.',
-        '  New goals are private to the owner and appended to the existing goal order.',
+        '  New goals are private to the owner and append unless --priority is supplied.',
         '',
         'Example:',
-        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --type keep',
-        '  sloth-agent goals create --name "Wedding" --target-amount 22000 --type spend --target-month 2027-06 --apply',
+        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --type keep --account-ref REF',
+        '  sloth-agent goals create --name "Wedding" --target-amount 22000 --type spend --account-ref REF --target-month 2027-06 --apply',
         '',
         'Output:',
-        '  Preview mode returns dryRun, method, endpoint, and payload.',
-        '  Apply mode returns the persisted goal and currency from the 201 response.',
+        '  Preview and apply return the Goal, currency, calculated forecastMonthKey,',
+        '  effective priority, funding-account details, and forecastBasis.',
     ].join('\n');
 }
 export function goalsUpdateHelpText() {
@@ -808,6 +843,7 @@ export function goalsUpdateHelpText() {
         '  --target-month YYYY-MM       Optional. Replace the target month.',
         '  --clear-target-month         Optional. Remove the target month.',
         '  --type keep|spend            Optional. Change how funded money is treated.',
+        '  --account-ref REF            Optional. Reassign to another personal Goal-funding account.',
         '  --priority POSITION          Optional. Positive whole-number position; 1 is highest.',
         '  --apply                      Optional. Write the partial update.',
         '  --base-url URL               Optional. Override the API origin.',
@@ -816,17 +852,13 @@ 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.',
+        '  Sloth recalculates the Goal roadmap before saving the update.',
         '  Set and clear target-month options are mutually exclusive.',
         '  Restore a spent goal before changing its type.',
-        '  Change active shared pot target amounts in the Sloth Budget app, where',
-        '  account balances can be reconciled across goals in priority order.',
-        '  Sharing remains app-managed. Updates to an already shared goal remain visible',
-        '  to the connected partner.',
+        '  Sharing remains app-managed. Updates to a shared Goal remain visible to the',
+        '  connected partner, but its assigned account remains private to the owner.',
         '',
         'Safety:',
         '  Without --apply, the command returns a dry-run preview and does not write.',
@@ -838,7 +870,8 @@ export function goalsUpdateHelpText() {
         '',
         'Output:',
         '  Preview mode returns dryRun, method, endpoint, and payload.',
-        '  Apply mode returns the complete persisted goal and currency.',
+        '  Apply mode returns the complete persisted Goal, calculated forecastMonthKey,',
+        '  effective priority, funding-account details, currency, and forecastBasis.',
     ].join('\n');
 }
 export function goalsMarkSpentHelpText() {
@@ -1171,6 +1204,7 @@ export function commandHelpText(topic) {
         'accounts-update': accountsUpdateHelpText,
         'accounts-remove': accountsRemoveHelpText,
         investments: investmentsHelpText,
+        portfolio: portfolioHelpText,
         budget: budgetHelpText,
         'budget-status': budgetStatusHelpText,
         'budget-move': budgetMoveHelpText,
@@ -1207,23 +1241,6 @@ 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;
 }
@@ -1404,7 +1421,11 @@ async function parseHttpResponse(response, token) {
             && typeof data.error === 'string')
             ? data.error
             : `Agent API request failed with status ${response.status}`;
-        throw new ApiError(redact(message, token), response.status);
+        const code = (data
+            && typeof data === 'object'
+            && 'code' in data
+            && typeof data.code === 'string') ? data.code : undefined;
+        throw new ApiError(redact(message, token), response.status, code);
     }
     return data;
 }
@@ -1891,7 +1912,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return 0;
         }
         if (parsed.command === 'goals-create') {
-            const endpoint = `${baseUrl}/api/agent/v1/goals`;
+            const endpoint = `${baseUrl}/api/agent/v1/goals${parsed.apply ? '' : '/preview'}`;
             const payload = {
                 name: parsed.name,
                 targetAmount: parsed.targetAmount,
@@ -1899,16 +1920,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                     ? {}
                     : { targetMonthKey: parsed.targetMonthKey }),
                 goalType: parsed.goalType,
+                fundingAccountRef: parsed.fundingAccountRef,
+                ...(parsed.priority === undefined ? {} : { priority: parsed.priority }),
             };
-            if (!parsed.apply) {
-                writeJson(writeStdout, {
-                    dryRun: true,
-                    endpoint,
-                    method: 'POST',
-                    payload,
-                });
-                return 0;
-            }
             const response = await fetchImplementation(endpoint, {
                 method: 'POST',
                 headers: {
@@ -1918,7 +1932,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 body: JSON.stringify(payload),
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
-            const data = parseApiResponse('goals-create', await parseHttpResponse(response, token));
+            const data = parseApiResponse(parsed.apply ? 'goals-create' : 'goals-preview', await parseHttpResponse(response, token));
             writeJson(writeStdout, data);
             return 0;
         }
@@ -1938,6 +1952,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                     ...(parsed.goalType === undefined
                         ? {}
                         : { goalType: parsed.goalType }),
+                    ...(parsed.fundingAccountRef === undefined
+                        ? {}
+                        : { fundingAccountRef: parsed.fundingAccountRef }),
                     ...(parsed.priority === undefined
                         ? {}
                         : { priority: parsed.priority }),
@@ -1962,9 +1979,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
-            writeJson(writeStdout, parsed.command !== 'goals-update' || parsed.priority === undefined
-                ? data
-                : withUpdatedGoalPriority(data, parsed.priority));
+            writeJson(writeStdout, data);
             return 0;
         }
         if (parsed.command === 'goals-delete') {
@@ -2059,7 +2074,7 @@ 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));
+            writeJson(writeStdout, data);
             return 0;
         }
         if (parsed.command === 'budget' || parsed.command === 'budget-status') {
@@ -2080,19 +2095,21 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         const path = parsed.command === 'accounts'
             ? '/api/agent/v1/accounts'
-            : parsed.command === 'investments'
-                ? `/api/agent/v1/investments${parsed.accountRef
-                    ? `?${new URLSearchParams({ accountRef: parsed.accountRef }).toString()}`
-                    : ''}`
-                : parsed.command === 'categories'
-                    ? '/api/agent/v1/categories'
-                    : `/api/agent/v1/transactions${(() => {
-                        const query = buildTransactionsQuery(parsed.filters);
-                        return query ? `?${query}` : '';
-                    })()}`;
+            : parsed.command === 'portfolio'
+                ? `/api/agent/v1/portfolio?${new URLSearchParams({ view: parsed.view }).toString()}`
+                : parsed.command === 'investments'
+                    ? `/api/agent/v1/investments${parsed.accountRef
+                        ? `?${new URLSearchParams({ accountRef: parsed.accountRef }).toString()}`
+                        : ''}`
+                    : parsed.command === 'categories'
+                        ? '/api/agent/v1/categories'
+                        : `/api/agent/v1/transactions${(() => {
+                            const query = buildTransactionsQuery(parsed.filters);
+                            return query ? `?${query}` : '';
+                        })()}`;
         const response = await fetchImplementation(`${baseUrl}${path}`, {
             method: 'GET',
-            headers: parsed.command === 'transactions'
+            headers: parsed.command === 'transactions' || parsed.command === 'portfolio'
                 ? { ...headers, Prefer: 'wait=45' }
                 : headers,
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -2104,7 +2121,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     catch (error) {
         const exitCode = error instanceof CliError ? error.exitCode : 1;
         const message = error instanceof Error ? error.message : String(error);
-        writeStderr(`${redact(message, token)}\n`);
+        const prefix = error instanceof ApiError && error.code ? `${error.code}: ` : '';
+        writeStderr(`${prefix}${redact(message, token)}\n`);
         return exitCode;
     }
 }

package/dist/contracts.js

@@ -610,6 +610,25 @@ function hasOnlyFields(value, fields) {
     const allowed = new Set(fields);
     return Object.keys(value).every((key) => allowed.has(key));
 }
+function isMonthKeyOrNull(value) {
+    return value === null || (typeof value === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value));
+}
+function isPlannedGoalFields(value) {
+    return (typeof value.name === 'string'
+        && value.name.trim().length > 0
+        && typeof value.targetAmount === 'number'
+        && Number.isFinite(value.targetAmount)
+        && value.targetAmount > 0
+        && isMonthKeyOrNull(value.targetMonthKey)
+        && isMonthKeyOrNull(value.forecastMonthKey)
+        && isGoalType(value.goalType)
+        && Number.isSafeInteger(value.effectivePriority)
+        && Number(value.effectivePriority) > 0
+        && isAccountRef(value.fundingAccountRef)
+        && typeof value.fundingAccountLabel === 'string'
+        && value.fundingAccountLabel.trim().length > 0);
+}
 function isGoal(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -617,20 +636,17 @@ function isGoal(value) {
             'name',
             'targetAmount',
             'targetMonthKey',
+            'forecastMonthKey',
             'goalType',
             'spentAt',
             'sharedWithPartner',
+            'effectivePriority',
+            'fundingAccountRef',
+            'fundingAccountLabel',
         ])
         && typeof value.id === 'string'
         && value.id.trim().length > 0
-        && typeof value.name === 'string'
-        && value.name.trim().length > 0
-        && (value.targetAmount === null
-            || (typeof value.targetAmount === 'number' && Number.isFinite(value.targetAmount)))
-        && (value.targetMonthKey === null
-            || (typeof value.targetMonthKey === 'string'
-                && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.targetMonthKey)))
-        && isGoalType(value.goalType)
+        && isPlannedGoalFields(value)
         && (value.goalType === 'spend'
             ? value.spentAt === null || isIsoDateTime(value.spentAt)
             : value.spentAt === null)
@@ -844,7 +860,8 @@ function isAccount(value) {
             'source',
             'lastBalanceUpdatedAt',
             'connectionState',
-            'isGoalSavingsSource',
+            'isGoalFundingAccount',
+            'partnerVisibility',
         ])
         && isAccountRef(value.accountRef)
         && isNullableNonEmptyString(value.accountName)
@@ -863,7 +880,10 @@ function isAccount(value) {
             || value.connectionState === 'expired'
             || value.connectionState === 'manual'
             || value.connectionState === 'unknown')
-        && typeof value.isGoalSavingsSource === 'boolean');
+        && typeof value.isGoalFundingAccount === 'boolean'
+        && (value.partnerVisibility === 'private'
+            || value.partnerVisibility === 'balance'
+            || value.partnerVisibility === 'holdings'));
 }
 function isAccountsResponse(value) {
     return (isObject(value)
@@ -929,19 +949,104 @@ function isInvestmentsResponse(value) {
                 && holdings.every(isInvestmentHolding));
         }));
 }
+function isPortfolioAccount(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'accountRef', 'ownerRole', 'accountName', 'institutionName', 'accountType',
+            'ownership', 'balanceAmount', 'currency', 'source', 'lastBalanceUpdatedAt',
+            'connectionState', 'partnerVisibility', 'isGoalFundingAccount', 'holdings',
+        ])
+        && isAccountRef(value.accountRef)
+        && (value.ownerRole === 'you' || value.ownerRole === 'partner')
+        && isNullableNonEmptyString(value.accountName)
+        && isNullableNonEmptyString(value.institutionName)
+        && (value.accountType === 'savings' || value.accountType === 'investments')
+        && (value.ownership === 'personal' || value.ownership === 'joint')
+        && (value.balanceAmount === null || (typeof value.balanceAmount === 'number' && Number.isFinite(value.balanceAmount)))
+        && isCurrency(value.currency)
+        && (value.source === 'connected' || value.source === 'manual')
+        && (value.lastBalanceUpdatedAt === null || isIsoDateTime(value.lastBalanceUpdatedAt))
+        && ['active', 'expired', 'manual', 'unknown'].includes(String(value.connectionState))
+        && ['private', 'balance', 'holdings'].includes(String(value.partnerVisibility))
+        && (value.isGoalFundingAccount === null || typeof value.isGoalFundingAccount === 'boolean')
+        && Array.isArray(value.holdings)
+        && value.holdings.every(isInvestmentHolding);
+}
+function isPortfolioResponse(value) {
+    if (!isObject(value) || !hasOnlyFields(value, [
+        'asOf', 'currency', 'view', 'hasPartner', 'totals',
+        'excludedCurrencyAccountCount', 'accounts', 'refresh',
+    ]))
+        return false;
+    const totals = value.totals;
+    const refresh = value.refresh;
+    return isIsoDateTime(value.asOf)
+        && isCurrency(value.currency)
+        && ['mine', 'partner', 'household'].includes(String(value.view))
+        && typeof value.hasPartner === 'boolean'
+        && isObject(totals)
+        && hasOnlyFields(totals, ['savingsAmount', 'investmentsAmount', 'trackedAmount'])
+        && ['savingsAmount', 'investmentsAmount', 'trackedAmount'].every(field => (typeof totals[field] === 'number' && Number.isFinite(totals[field])))
+        && Number.isSafeInteger(value.excludedCurrencyAccountCount)
+        && Number(value.excludedCurrencyAccountCount) >= 0
+        && Array.isArray(value.accounts)
+        && value.accounts.every(isPortfolioAccount)
+        && isObject(refresh)
+        && hasOnlyFields(refresh, ['status', 'reason', 'utcDate'])
+        && ['skipped', 'completed', 'in_progress', 'partial', 'failed'].includes(String(refresh.status))
+        && typeof refresh.reason === 'string'
+        && refresh.reason.length > 0
+        && isIsoDate(refresh.utcDate);
+}
+function isForecastBasis(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'calculatedAt',
+            'activeScenarioRevision',
+            'projectionThroughMonthKey',
+        ])
+        && isIsoDateTime(value.calculatedAt)
+        && Number.isSafeInteger(value.activeScenarioRevision)
+        && Number(value.activeScenarioRevision) >= 0
+        && isMonthKeyOrNull(value.projectionThroughMonthKey) === true
+        && value.projectionThroughMonthKey !== null;
+}
+function isGoalPreview(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'name',
+            'targetAmount',
+            'targetMonthKey',
+            'forecastMonthKey',
+            'goalType',
+            'effectivePriority',
+            'fundingAccountRef',
+            'fundingAccountLabel',
+        ])
+        && isPlannedGoalFields(value);
+}
 function isGoalsResponse(value) {
     return (isObject(value)
-        && hasOnlyFields(value, ['currency', 'goals'])
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goals'])
         && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
         && Array.isArray(value.goals)
         && value.goals.every(isGoal));
 }
 function isGoalMutationResponse(value) {
     return (isObject(value)
-        && hasOnlyFields(value, ['currency', 'goal'])
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goal'])
         && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
         && isGoal(value.goal));
 }
+function isGoalPreviewResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'goal'])
+        && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
+        && isGoalPreview(value.goal);
+}
 function isGoalDeleteResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, ['deleted', 'deletedGoalId'])
@@ -1007,45 +1112,49 @@ export function parseApiResponse(command, value) {
                 ? isAccountRemovalResponse(value)
                 : command === 'investments'
                     ? isInvestmentsResponse(value)
-                    : command === 'budget' || command === 'budget-update'
-                        ? isBudgetResponse(value)
-                        : command === 'budget-status'
-                            ? isBudgetActivityStatusResponse(value)
-                            : command === 'budget-move'
-                                ? isBudgetMovementResponse(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 === 'rules-list'
-                                                    ? isNotificationRuleListResponse(value)
-                                                    : command === 'rules-get' || command === 'rules-set'
-                                                        ? isNotificationRuleResponse(value)
-                                                        : command === 'rules-delete'
-                                                            ? isNotificationRuleDeleteResponse(value)
-                                                            : command === 'rules-scan-contract'
-                                                                ? isRenewalExtractionResponse(value)
-                                                                : command === 'receipts-extract'
-                                                                    ? isReceiptExtractResponse(value)
-                                                                    : command === 'receipts-get'
-                                                                        ? isReceiptLookupResponse(value)
-                                                                        : command === 'receipts-attach'
-                                                                            ? isReceiptMutationResponse(value)
-                                                                            : command === 'receipts-remove'
-                                                                                ? isReceiptDeleteResponse(value)
-                                                                                : command === 'assign'
-                                                                                    ? isAssignmentResponse(value)
-                                                                                    : command === 'ask-partner'
-                                                                                        ? isPartnerResponse(value)
-                                                                                        : command === 'goals-list'
-                                                                                            ? isGoalsResponse(value)
-                                                                                            : command === 'goals-delete'
-                                                                                                ? isGoalDeleteResponse(value)
-                                                                                                : isGoalMutationResponse(value);
+                    : command === 'portfolio'
+                        ? isPortfolioResponse(value)
+                        : command === 'budget' || command === 'budget-update'
+                            ? isBudgetResponse(value)
+                            : command === 'budget-status'
+                                ? isBudgetActivityStatusResponse(value)
+                                : command === 'budget-move'
+                                    ? isBudgetMovementResponse(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 === 'rules-list'
+                                                        ? isNotificationRuleListResponse(value)
+                                                        : command === 'rules-get' || command === 'rules-set'
+                                                            ? isNotificationRuleResponse(value)
+                                                            : command === 'rules-delete'
+                                                                ? isNotificationRuleDeleteResponse(value)
+                                                                : command === 'rules-scan-contract'
+                                                                    ? isRenewalExtractionResponse(value)
+                                                                    : command === 'receipts-extract'
+                                                                        ? isReceiptExtractResponse(value)
+                                                                        : command === 'receipts-get'
+                                                                            ? isReceiptLookupResponse(value)
+                                                                            : command === 'receipts-attach'
+                                                                                ? isReceiptMutationResponse(value)
+                                                                                : command === 'receipts-remove'
+                                                                                    ? isReceiptDeleteResponse(value)
+                                                                                    : command === 'assign'
+                                                                                        ? isAssignmentResponse(value)
+                                                                                        : command === 'ask-partner'
+                                                                                            ? isPartnerResponse(value)
+                                                                                            : command === 'goals-list'
+                                                                                                ? isGoalsResponse(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/dist/errors.js

@@ -17,8 +17,10 @@ export class ConfigError extends CliError {
 }
 export class ApiError extends CliError {
     status;
-    constructor(message, status) {
+    code;
+    constructor(message, status, code) {
         super(message, 1);
         this.status = status;
+        this.code = code;
     }
 }

package/package.json

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