@slothmoney/agent-cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.6.0 - 2026-08-08
+
+- Expose goal-savings membership on account inventory rows and preview or apply
+  owner-authorized changes through opaque account references.
+- Read cache-only linked investment portfolios with provider-native holdings,
+  quantities, valuations, currencies, and freshness metadata.
+- Keep strict response validation, JSON-only stdout, command-specific help,
+  and clean-install package coverage synchronized with Agent API v1.
+
 ## 0.5.0 - 2026-08-07
 
 - Create and rename custom categories, with existing icon and category type

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect known accounts, manage goals, and categorise transactions through the
+Use your own agent to inspect accounts and investment holdings, manage goals, and categorise transactions through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.5.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.6.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -24,10 +24,10 @@ 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`,
+New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`,
 `categories`, `transactions`, and `goals` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
-or line items, ask a partner for an explanation, or manage goals. Token
+or line items, change goal-savings account membership, ask a partner for an explanation, or manage goals. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -250,11 +250,41 @@ 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`, and `connectionState`. Missing values are JSON
+known, `lastBalanceUpdatedAt`, `connectionState`, and `isGoalSavingsSource`.
+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
 visibility rules.
 
+Goal-savings changes are previews unless `--apply` is present. Only
+caller-owned connected accounts can be changed; partner-owned shared accounts
+and fixed manual accounts return an explanatory error.
+
+```bash
+sloth-agent accounts update \
+  --account-ref sloth_account_v1_... \
+  --goal-savings-source true
+
+sloth-agent accounts update \
+  --account-ref sloth_account_v1_... \
+  --goal-savings-source true \
+  --apply
+```
+
+Read linked investment accounts and their cached holdings:
+
+```bash
+sloth-agent investments
+sloth-agent investments --account-ref sloth_account_v1_...
+```
+
+Investment reads are cache-only and do not refresh a brokerage. Holding
+quantities, unit prices, market values, currencies, and freshness are returned
+in provider-native terms. They are not converted or guaranteed to reconcile
+to an account total reported in another currency. Caller-owned personal and
+joint linked investment accounts are included; partner-owned accounts, manual
+holdings, and investment activities are not.
+
 List your goals:
 
 ```bash

package/dist/args.js

@@ -226,6 +226,54 @@ function requiredOption(values, option, commandLabel) {
         throw new UsageError(`${commandLabel} requires ${option} <value>`);
     return value;
 }
+function parseAccountRef(value) {
+    if (!/^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value)) {
+        throw new UsageError('--account-ref must be a valid accountRef from sloth-agent accounts');
+    }
+    return value;
+}
+function parseAccounts(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0)
+            throw new UsageError(`Unknown accounts option: ${args[0]}`);
+        return withBaseUrl({ command: 'accounts' }, baseUrl);
+    }
+    if (subcommand === 'update') {
+        const { values, apply } = parseNamedOptions(args, 'accounts update', new Set(['--account-ref', '--goal-savings-source']));
+        const source = requiredOption(values, '--goal-savings-source', 'accounts update');
+        if (source !== 'true' && source !== 'false') {
+            throw new UsageError('--goal-savings-source must be true or false');
+        }
+        return withBaseUrl({
+            command: 'accounts-update',
+            accountRef: parseAccountRef(requiredOption(values, '--account-ref', 'accounts update')),
+            isGoalSavingsSource: source === 'true',
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand.startsWith('-')) {
+        throw new UsageError(`Unknown accounts option: ${subcommand}`);
+    }
+    throw new UsageError(`Unknown accounts command: ${subcommand}`);
+}
+function parseInvestments(args, baseUrl) {
+    let accountRef;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--account-ref') {
+            accountRef = setOnce(accountRef, parseAccountRef(readOptionValue(args, index, '--account-ref')), '--account-ref');
+            index += 1;
+        }
+        else if (argument.startsWith('--account-ref=')) {
+            accountRef = setOnce(accountRef, parseAccountRef(requireNonEmpty(argument.slice('--account-ref='.length), '--account-ref')), '--account-ref');
+        }
+        else {
+            throw new UsageError(`Unknown investments option: ${argument}`);
+        }
+    }
+    return withBaseUrl({ command: 'investments', ...(accountRef ? { accountRef } : {}) }, baseUrl);
+}
 function parseCategories(args, baseUrl) {
     const subcommand = args.shift();
     if (subcommand === undefined || subcommand === 'list') {
@@ -555,8 +603,12 @@ function helpTopic(argv) {
         || command === 'transactions'
         || command === 'assign'
         || command === 'ask-partner') {
+        if (command === 'accounts' && subcommand === 'update')
+            return 'accounts-update';
         return command;
     }
+    if (command === 'investments')
+        return 'investments';
     return undefined;
 }
 export function parseArgs(argv) {
@@ -583,10 +635,10 @@ export function parseArgs(argv) {
         return parseLineItems(args, baseUrl);
     }
     if (command === 'accounts') {
-        if (args.length > 0) {
-            throw new UsageError(`Unknown accounts option: ${args[0]}`);
-        }
-        return withBaseUrl({ command }, baseUrl);
+        return parseAccounts(args, baseUrl);
+    }
+    if (command === 'investments') {
+        return parseInvestments(args, baseUrl);
     }
     if (command === 'transactions') {
         return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);

package/dist/cli.js

@@ -4,7 +4,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.5.0';
+export const CLI_VERSION = '0.6.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -25,7 +25,9 @@ export function usageText() {
         '  sloth-agent auth login [--token-stdin | --from-env] [--base-url URL]',
         '  sloth-agent auth status [--base-url URL]',
         '  sloth-agent auth logout [--base-url URL]',
-        '  sloth-agent accounts [--base-url URL]',
+        '  sloth-agent accounts [list] [--base-url URL]',
+        '  sloth-agent accounts update --account-ref REF --goal-savings-source true|false [--apply]',
+        '  sloth-agent investments [--account-ref REF] [--base-url URL]',
         '  sloth-agent categories [list] [--base-url URL]',
         '  sloth-agent categories create --name NAME --icon-key KEY --type TYPE [--apply]',
         '  sloth-agent categories rename --category-id ID --name NAME [--apply]',
@@ -280,7 +282,7 @@ export function accountsHelpText() {
         'Read the existing Sloth account inventory known to the authenticated user.',
         '',
         'Usage:',
-        '  sloth-agent accounts [--base-url URL]',
+        '  sloth-agent accounts [list] [--base-url URL]',
         '',
         'Options:',
         '  --base-url URL   Optional. Override the API origin.',
@@ -296,6 +298,57 @@ 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',
+    ].join('\n');
+}
+export function accountsUpdateHelpText() {
+    return [
+        'Sloth Agent CLI — accounts update',
+        '',
+        'Preview or update whether an owned connected account is used for goal savings.',
+        '',
+        'Usage:',
+        '  sloth-agent accounts update --account-ref REF --goal-savings-source true|false [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --account-ref REF                  Opaque accountRef from sloth-agent accounts.',
+        '  --goal-savings-source true|false   Enable or disable goal-savings membership.',
+        '',
+        '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.',
+        '  Partner-owned shared accounts and manual accounts cannot be changed.',
+        '  Unknown, disconnected, or inaccessible references return Account not found.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, endpoint, and payload.',
+        '  Apply mode returns changed and the complete persisted account.',
+    ].join('\n');
+}
+export function investmentsHelpText() {
+    return [
+        'Sloth Agent CLI — investments',
+        '',
+        'Read linked investment accounts and their cached provider-native holdings.',
+        '',
+        'Usage:',
+        '  sloth-agent investments [--account-ref REF] [--base-url URL]',
+        '',
+        'Options:',
+        '  --account-ref REF  Optional. Return one linked investment account.',
+        '  --base-url URL     Optional. Override the API origin.',
+        '  -h, --help         Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access:',
+        '  This command requires agent:read and is read-only and cache-only; it never refreshes a brokerage.',
+        '  An unknown or non-investment filter returns Investment account not found.',
+        '',
+        'Output:',
+        '  investmentAccounts contains account totals and nested holdings.',
+        '  Holding quantities, prices, market values, currencies, and freshness are',
+        '  provider-native and are not converted or guaranteed to reconcile to totals.',
     ].join('\n');
 }
 export function transactionsHelpText() {
@@ -581,6 +634,8 @@ export function commandHelpText(topic) {
         'auth-status': authStatusHelpText,
         'auth-logout': authLogoutHelpText,
         accounts: accountsHelpText,
+        'accounts-update': accountsUpdateHelpText,
+        investments: investmentsHelpText,
         categories: categoriesHelpText,
         'categories-create': categoriesCreateHelpText,
         'categories-rename': categoriesRenameHelpText,
@@ -833,9 +888,32 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        if (parsed.command === 'accounts-update' && !parsed.apply) {
+            const endpoint = `${baseUrl}/api/agent/v1/accounts/${encodeURIComponent(parsed.accountRef)}`;
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint,
+                method: 'PATCH',
+                payload: { isGoalSavingsSource: parsed.isGoalSavingsSource },
+            });
+            return 0;
+        }
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
+        if (parsed.command === 'accounts-update') {
+            const endpoint = `${baseUrl}/api/agent/v1/accounts/${encodeURIComponent(parsed.accountRef)}`;
+            const payload = { isGoalSavingsSource: parsed.isGoalSavingsSource };
+            const response = await fetchImplementation(endpoint, {
+                method: 'PATCH',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         if (parsed.command === 'categories-create'
             || parsed.command === 'categories-rename'
             || parsed.command === 'line-items-create'
@@ -1004,12 +1082,16 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         const path = parsed.command === 'accounts'
             ? '/api/agent/v1/accounts'
-            : parsed.command === 'categories'
-                ? '/api/agent/v1/categories'
-                : `/api/agent/v1/transactions${(() => {
-                    const query = buildTransactionsQuery(parsed.filters);
-                    return query ? `?${query}` : '';
-                })()}`;
+            : 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'

package/dist/contracts.js

@@ -303,6 +303,7 @@ function isAccount(value) {
             'source',
             'lastBalanceUpdatedAt',
             'connectionState',
+            'isGoalSavingsSource',
         ])
         && typeof value.accountRef === 'string'
         && /^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value.accountRef)
@@ -321,7 +322,8 @@ function isAccount(value) {
         && (value.connectionState === 'active'
             || value.connectionState === 'expired'
             || value.connectionState === 'manual'
-            || value.connectionState === 'unknown'));
+            || value.connectionState === 'unknown')
+        && typeof value.isGoalSavingsSource === 'boolean');
 }
 function isAccountsResponse(value) {
     return (isObject(value)
@@ -330,6 +332,56 @@ function isAccountsResponse(value) {
         && Array.isArray(value.accounts)
         && value.accounts.every(isAccount));
 }
+function isAccountMutationResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['changed', 'account'])
+        && typeof value.changed === 'boolean'
+        && isAccount(value.account));
+}
+function isInvestmentHolding(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, [
+            'instrumentType',
+            'symbol',
+            'name',
+            'units',
+            'unitPriceAmount',
+            'marketValueAmount',
+            'currency',
+            'providerFreshnessAsOf',
+            'syncedAt',
+        ])
+        && typeof value.instrumentType === 'string'
+        && value.instrumentType.trim().length > 0
+        && (value.symbol === null || (typeof value.symbol === 'string' && value.symbol.trim().length > 0))
+        && typeof value.name === 'string'
+        && value.name.trim().length > 0
+        && typeof value.units === 'number'
+        && Number.isFinite(value.units)
+        && typeof value.unitPriceAmount === 'number'
+        && Number.isFinite(value.unitPriceAmount)
+        && typeof value.marketValueAmount === 'number'
+        && Number.isFinite(value.marketValueAmount)
+        && isCurrency(value.currency)
+        && (value.providerFreshnessAsOf === null || isIsoDateTime(value.providerFreshnessAsOf))
+        && isIsoDateTime(value.syncedAt));
+}
+function isInvestmentsResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['asOf', 'investmentAccounts'])
+        && isIsoDateTime(value.asOf)
+        && Array.isArray(value.investmentAccounts)
+        && value.investmentAccounts.every((account) => {
+            if (!isObject(account))
+                return false;
+            const { holdings, ...baseAccount } = account;
+            return (isAccount(baseAccount)
+                && account.accountType === 'investments'
+                && account.source === 'connected'
+                && Array.isArray(holdings)
+                && holdings.every(isInvestmentHolding));
+        }));
+}
 function isGoalsResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, ['currency', 'goals'])
@@ -353,23 +405,27 @@ function isGoalDeleteResponse(value) {
 export function parseApiResponse(command, value) {
     const valid = command === 'accounts'
         ? isAccountsResponse(value)
-        : command === 'categories'
-            ? isCategoryResponse(value)
-            : command === 'categories-create' || command === 'categories-rename'
-                ? isCategoryMutationResponse(value)
-                : command === 'line-items-create' || command === 'line-items-rename'
-                    ? isLineItemMutationResponse(value)
-                    : command === 'transactions'
-                        ? isTransactionsResponse(value)
-                        : command === 'assign'
-                            ? isAssignmentResponse(value)
-                            : command === 'ask-partner'
-                                ? isPartnerResponse(value)
-                                : command === 'goals-list'
-                                    ? isGoalsResponse(value)
-                                    : command === 'goals-delete'
-                                        ? isGoalDeleteResponse(value)
-                                        : isGoalMutationResponse(value);
+        : command === 'accounts-update'
+            ? isAccountMutationResponse(value)
+            : command === 'investments'
+                ? isInvestmentsResponse(value)
+                : command === 'categories'
+                    ? isCategoryResponse(value)
+                    : command === 'categories-create' || command === 'categories-rename'
+                        ? isCategoryMutationResponse(value)
+                        : command === 'line-items-create' || command === 'line-items-rename'
+                            ? isLineItemMutationResponse(value)
+                            : command === 'transactions'
+                                ? isTransactionsResponse(value)
+                                : command === 'assign'
+                                    ? isAssignmentResponse(value)
+                                    : command === 'ask-partner'
+                                        ? isPartnerResponse(value)
+                                        : command === 'goals-list'
+                                            ? isGoalsResponse(value)
+                                            : command === 'goals-delete'
+                                                ? isGoalDeleteResponse(value)
+                                                : isGoalMutationResponse(value);
     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.5.0",
+  "version": "0.6.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {