@slothmoney/agent-cli 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.9.0 - 2026-08-12
+
+- Manage owned manual balance and manual transaction accounts through partial
+  account updates, including metadata, ownership, balance-only settings, and
+  goal-savings membership where supported.
+- Preview or apply idempotent manual account archival while retaining the
+  underlying account, transaction, import, balance, and categorisation records.
+- Keep account writes local-only by default and require `--apply` before any
+  authenticated PATCH or DELETE request is sent.
+
 ## 0.8.0 - 2026-08-12
 
 - Read each goal's one-based priority and move one goal to a new position with

package/README.md

@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.8.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.9.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -27,7 +27,7 @@ where the CLI runs.
 New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`,
 `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, update planned budgets, change goal-savings account membership, ask a partner for an explanation, or manage goals. Token
+or line items, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -305,21 +305,38 @@ Missing values are JSON
 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.
+Account changes are previews unless `--apply` is present. Connected accounts
+support only goal-savings membership. Manual current accounts support their
+institution, name, currency, and ownership. Manual balance accounts also
+support balance, Savings/Investments type, and goal-savings membership.
+Partner-owned shared accounts return an explanatory error.
 
 ```bash
 sloth-agent accounts update \
   --account-ref sloth_account_v1_... \
-  --goal-savings-source true
+  --institution-name "Hargreaves Lansdown" \
+  --account-name "Stocks & Shares ISA" \
+  --currency GBP \
+  --ownership individual \
+  --balance-amount 12500.75 \
+  --account-type investments \
+  --goal-savings-source false
 
 sloth-agent accounts update \
   --account-ref sloth_account_v1_... \
-  --goal-savings-source true \
+  --goal-savings-source false \
   --apply
 ```
 
+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`.
+
+```bash
+sloth-agent accounts remove --account-ref sloth_account_v1_...
+sloth-agent accounts remove --account-ref sloth_account_v1_... --apply
+```
+
 Read linked investment accounts and their cached holdings:
 
 ```bash

package/dist/args.js

@@ -242,6 +242,19 @@ function parseAccountRef(value) {
     }
     return value;
 }
+function parseAccountName(value, option) {
+    const name = value.trim();
+    if (name.length > 300)
+        throw new UsageError(`${option} must be at most 300 characters`);
+    return name;
+}
+function parseAccountBalance(value) {
+    const amount = Number(value);
+    if (!/^\d+(?:\.\d+)?$/.test(value) || !Number.isFinite(amount) || amount < 0) {
+        throw new UsageError('--balance-amount must be a nonnegative amount');
+    }
+    return amount;
+}
 function parseAccounts(args, baseUrl) {
     const subcommand = args.shift();
     if (subcommand === undefined || subcommand === 'list') {
@@ -250,15 +263,71 @@ function parseAccounts(args, baseUrl) {
         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') {
+        const { values, apply } = parseNamedOptions(args, 'accounts update', new Set([
+            '--account-ref',
+            '--institution-name',
+            '--account-name',
+            '--currency',
+            '--ownership',
+            '--balance-amount',
+            '--account-type',
+            '--goal-savings-source',
+        ]));
+        const institutionName = values.get('--institution-name');
+        const accountName = values.get('--account-name');
+        const currencyValue = values.get('--currency');
+        const ownershipValue = values.get('--ownership');
+        const balanceValue = values.get('--balance-amount');
+        const accountTypeValue = values.get('--account-type');
+        const sourceValue = values.get('--goal-savings-source');
+        if (currencyValue !== undefined && !/^[A-Za-z]{3}$/.test(currencyValue)) {
+            throw new UsageError('--currency must be a three-letter currency code');
+        }
+        if (ownershipValue !== undefined
+            && ownershipValue !== 'individual'
+            && ownershipValue !== 'joint') {
+            throw new UsageError('--ownership must be individual or joint');
+        }
+        if (accountTypeValue !== undefined
+            && accountTypeValue !== 'savings'
+            && accountTypeValue !== 'investments') {
+            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');
         }
+        const update = {
+            ...(institutionName === undefined
+                ? {}
+                : { institutionName: parseAccountName(institutionName, '--institution-name') }),
+            ...(accountName === undefined
+                ? {}
+                : { accountName: parseAccountName(accountName, '--account-name') }),
+            ...(currencyValue === undefined ? {} : { currency: currencyValue.toUpperCase() }),
+            ...(ownershipValue === undefined
+                ? {}
+                : { ownership: ownershipValue === 'individual' ? 'personal' : 'joint' }),
+            ...(balanceValue === undefined ? {} : { balanceAmount: parseAccountBalance(balanceValue) }),
+            ...(accountTypeValue === undefined
+                ? {}
+                : { accountType: accountTypeValue }),
+            ...(sourceValue === undefined ? {} : { isGoalSavingsSource: sourceValue === 'true' }),
+        };
+        if (Object.keys(update).length === 0) {
+            throw new UsageError('accounts update requires at least one field to update');
+        }
         return withBaseUrl({
             command: 'accounts-update',
             accountRef: parseAccountRef(requiredOption(values, '--account-ref', 'accounts update')),
-            isGoalSavingsSource: source === 'true',
+            update,
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'remove') {
+        const { values, apply } = parseNamedOptions(args, 'accounts remove', new Set(['--account-ref']));
+        return withBaseUrl({
+            command: 'accounts-remove',
+            accountRef: parseAccountRef(requiredOption(values, '--account-ref', 'accounts remove')),
             apply,
         }, baseUrl);
     }
@@ -657,6 +726,8 @@ function helpTopic(argv) {
         || command === 'ask-partner') {
         if (command === 'accounts' && subcommand === 'update')
             return 'accounts-update';
+        if (command === 'accounts' && subcommand === 'remove')
+            return 'accounts-remove';
         return command;
     }
     if (command === 'investments')

package/dist/cli.js

@@ -4,7 +4,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, validateAssignmentPayload, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.8.0';
+export const CLI_VERSION = '0.9.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -26,7 +26,8 @@ export function usageText() {
         '  sloth-agent auth status [--base-url URL]',
         '  sloth-agent auth logout [--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 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 budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
@@ -308,19 +309,29 @@ export function accountsUpdateHelpText() {
     return [
         'Sloth Agent CLI — accounts update',
         '',
-        'Preview or update whether an owned connected account is used for goal savings.',
+        'Preview or update an owned account. Manual accounts support their editable fields.',
         '',
         'Usage:',
-        '  sloth-agent accounts update --account-ref REF --goal-savings-source true|false [--apply] [--base-url URL]',
+        '  sloth-agent accounts update --account-ref REF [fields] [--apply] [--base-url URL]',
         '',
-        'Required inputs:',
+        'Required input:',
         '  --account-ref REF                  Opaque accountRef from sloth-agent accounts.',
-        '  --goal-savings-source true|false   Enable or disable goal-savings membership.',
+        '',
+        'Update fields (at least one):',
+        '  --institution-name NAME            Manual account institution.',
+        '  --account-name NAME                Manual account name.',
+        '  --currency CODE                    Three-letter currency code.',
+        '  --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.',
         '',
         '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.',
+        '  Connected accounts support only --goal-savings-source.',
+        '  Manual current accounts cannot change type, balance, or goal-savings membership.',
+        '  Partner-owned shared accounts cannot be changed.',
         '  Unknown, disconnected, or inaccessible references return Account not found.',
         ...API_ORIGIN_HELP_LINES,
         '',
@@ -329,6 +340,30 @@ export function accountsUpdateHelpText() {
         '  Apply mode returns changed and the complete persisted account.',
     ].join('\n');
 }
+export function accountsRemoveHelpText() {
+    return [
+        'Sloth Agent CLI — accounts remove',
+        '',
+        'Preview or archive an owned manual account while retaining its underlying records.',
+        '',
+        'Usage:',
+        '  sloth-agent accounts remove --account-ref REF [--apply] [--base-url URL]',
+        '',
+        'Required input:',
+        '  --account-ref REF  Opaque accountRef from sloth-agent accounts.',
+        '',
+        'Write behavior:',
+        '  Without --apply, returns a JSON preview without credentials or a network request.',
+        '  With --apply, requires agent:write and archives the manual account.',
+        '  Connected and partner-owned accounts cannot be removed.',
+        '  Repeating an applied removal succeeds with changed false.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, and endpoint.',
+        '  Apply mode returns removed, changed, and accountRef.',
+    ].join('\n');
+}
 export function investmentsHelpText() {
     return [
         'Sloth Agent CLI — investments',
@@ -711,6 +746,7 @@ export function commandHelpText(topic) {
         'auth-logout': authLogoutHelpText,
         accounts: accountsHelpText,
         'accounts-update': accountsUpdateHelpText,
+        'accounts-remove': accountsRemoveHelpText,
         investments: investmentsHelpText,
         budget: budgetHelpText,
         'budget-update': budgetUpdateHelpText,
@@ -998,7 +1034,16 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 dryRun: true,
                 endpoint,
                 method: 'PATCH',
-                payload: { isGoalSavingsSource: parsed.isGoalSavingsSource },
+                payload: parsed.update,
+            });
+            return 0;
+        }
+        if (parsed.command === 'accounts-remove' && !parsed.apply) {
+            const endpoint = `${baseUrl}/api/agent/v1/accounts/${encodeURIComponent(parsed.accountRef)}`;
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint,
+                method: 'DELETE',
             });
             return 0;
         }
@@ -1023,11 +1068,21 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         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),
+                body: JSON.stringify(parsed.update),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'accounts-remove') {
+            const endpoint = `${baseUrl}/api/agent/v1/accounts/${encodeURIComponent(parsed.accountRef)}`;
+            const response = await fetchImplementation(endpoint, {
+                method: 'DELETE',
+                headers,
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
             const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));

package/dist/contracts.js

@@ -423,6 +423,14 @@ function isAccountMutationResponse(value) {
         && typeof value.changed === 'boolean'
         && isAccount(value.account));
 }
+function isAccountRemovalResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['removed', 'changed', 'accountRef'])
+        && value.removed === true
+        && typeof value.changed === 'boolean'
+        && typeof value.accountRef === 'string'
+        && /^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value.accountRef));
+}
 function isInvestmentHolding(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -492,27 +500,29 @@ export function parseApiResponse(command, value) {
         ? isAccountsResponse(value)
         : command === 'accounts-update'
             ? isAccountMutationResponse(value)
-            : command === 'investments'
-                ? isInvestmentsResponse(value)
-                : command === 'budget' || command === 'budget-update'
-                    ? isBudgetResponse(value)
-                    : command === 'categories'
-                        ? isCategoryResponse(value)
-                        : command === 'categories-create' || command === 'categories-rename'
-                            ? isCategoryMutationResponse(value)
-                            : command === 'line-items-create' || command === 'line-items-rename'
-                                ? isLineItemMutationResponse(value)
-                                : command === 'transactions'
-                                    ? isTransactionsResponse(value)
-                                    : command === 'assign'
-                                        ? isAssignmentResponse(value)
-                                        : command === 'ask-partner'
-                                            ? isPartnerResponse(value)
-                                            : command === 'goals-list'
-                                                ? isGoalsResponse(value)
-                                                : command === 'goals-delete'
-                                                    ? isGoalDeleteResponse(value)
-                                                    : isGoalMutationResponse(value);
+            : command === 'accounts-remove'
+                ? isAccountRemovalResponse(value)
+                : command === 'investments'
+                    ? isInvestmentsResponse(value)
+                    : command === 'budget' || command === 'budget-update'
+                        ? isBudgetResponse(value)
+                        : command === 'categories'
+                            ? isCategoryResponse(value)
+                            : command === 'categories-create' || command === 'categories-rename'
+                                ? isCategoryMutationResponse(value)
+                                : command === 'line-items-create' || command === 'line-items-rename'
+                                    ? isLineItemMutationResponse(value)
+                                    : command === 'transactions'
+                                        ? isTransactionsResponse(value)
+                                        : command === 'assign'
+                                            ? isAssignmentResponse(value)
+                                            : command === 'ask-partner'
+                                                ? isPartnerResponse(value)
+                                                : command === 'goals-list'
+                                                    ? isGoalsResponse(value)
+                                                    : command === 'goals-delete'
+                                                        ? isGoalDeleteResponse(value)
+                                                        : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/package.json

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