@slothmoney/agent-cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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

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 `isGoalFundingAccount`.
+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,7 +606,7 @@ 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-funding eligibility. 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-funding eligibility.
 Partner-owned shared accounts return an explanatory error.
@@ -618,14 +620,31 @@ sloth-agent accounts update \
   --ownership individual \
   --balance-amount 12500.75 \
   --account-type investments \
-  --goal-funding-account false
+  --goal-funding-account false \
+  --partner-visibility holdings
 
 sloth-agent accounts update \
   --account-ref sloth_account_v1_... \
-  --goal-funding-account 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`.

package/dist/args.js

@@ -390,6 +390,7 @@ function parseAccounts(args, baseUrl) {
             '--balance-amount',
             '--account-type',
             '--goal-funding-account',
+            '--partner-visibility',
         ]));
         const institutionName = values.get('--institution-name');
         const accountName = values.get('--account-name');
@@ -398,6 +399,7 @@ function parseAccounts(args, baseUrl) {
         const balanceValue = values.get('--balance-amount');
         const accountTypeValue = values.get('--account-type');
         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');
         }
@@ -414,6 +416,12 @@ function parseAccounts(args, baseUrl) {
         if (sourceValue !== undefined && sourceValue !== 'true' && sourceValue !== '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
                 ? {}
@@ -430,6 +438,9 @@ function parseAccounts(args, baseUrl) {
                 ? {}
                 : { accountType: accountTypeValue }),
             ...(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()
@@ -979,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) {
@@ -1015,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.19.0';
+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]',
@@ -378,11 +379,14 @@ export function accountsUpdateHelpText() {
         '  --balance-amount AMOUNT             Balance-only account balance.',
         '  --account-type savings|investments Balance-only account type.',
         '  --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-funding-account.',
+        '  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.',
@@ -442,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',
@@ -1173,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,
@@ -2063,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),

package/dist/contracts.js

@@ -861,6 +861,7 @@ function isAccount(value) {
             'lastBalanceUpdatedAt',
             'connectionState',
             'isGoalFundingAccount',
+            'partnerVisibility',
         ])
         && isAccountRef(value.accountRef)
         && isNullableNonEmptyString(value.accountName)
@@ -879,7 +880,10 @@ function isAccount(value) {
             || value.connectionState === 'expired'
             || value.connectionState === 'manual'
             || value.connectionState === 'unknown')
-        && typeof value.isGoalFundingAccount === 'boolean');
+        && typeof value.isGoalFundingAccount === 'boolean'
+        && (value.partnerVisibility === 'private'
+            || value.partnerVisibility === 'balance'
+            || value.partnerVisibility === 'holdings'));
 }
 function isAccountsResponse(value) {
     return (isObject(value)
@@ -945,6 +949,55 @@ 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, [
@@ -1059,47 +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-preview'
-                                                                                                ? isGoalPreviewResponse(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/package.json

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