@slothmoney/agent-cli 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.14.0 - 2026-08-20
+
+- Add `transactions --account-ref REF` using the opaque reference returned by
+  `sloth-agent accounts`, while retaining `--account-id` for compatibility.
+- Require every transaction result to include its matching `accountRef`.
+
 ## 0.13.0 - 2026-08-19
 
 - Let `assign` share or unshare an owned booked personal transaction, update

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.13.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.14.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -471,6 +471,20 @@ Missing values are JSON
 are excluded, while enabled shared joint accounts follow Sloth's existing
 visibility rules.
 
+Use an account's opaque reference to read only its transactions. Transaction
+rows return the same `accountRef`, so pagination and follow-up reads keep the
+account boundary explicit:
+
+```bash
+sloth-agent transactions \
+  --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE \
+  --limit 50
+```
+
+Copy the value from `sloth-agent accounts`. The older `--account-id` filter is
+still accepted for compatibility, but new workflows should use
+`--account-ref`. Do not provide both filters in one command.
+
 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

package/dist/account-ref.js

@@ -0,0 +1,4 @@
+const ACCOUNT_REF_PATTERN = /^sloth_account_v1_[A-Za-z0-9_-]{43}$/;
+export function isAccountRef(value) {
+    return typeof value === 'string' && ACCOUNT_REF_PATTERN.test(value);
+}

package/dist/args.js

@@ -1,4 +1,5 @@
 import { UsageError } from './errors.js';
+import { isAccountRef } from './account-ref.js';
 import { CATEGORY_TYPES, ICON_KEYS, } from './category-metadata.js';
 import { isGoalType, } from './goal-metadata.js';
 const PRODUCTION_BASE_URL = 'https://budget.slothmoney.app';
@@ -175,6 +176,7 @@ function parseTransactions(args) {
             '--start-date',
             '--end-date',
             '--q',
+            '--account-ref',
             '--account-id',
             '--category-id',
             '--line-item-id',
@@ -208,6 +210,9 @@ function parseTransactions(args) {
         else if (name === '--q') {
             filters.q = setOnce(filters.q, value, name);
         }
+        else if (name === '--account-ref') {
+            filters.accountRef = setOnce(filters.accountRef, parseAccountRef(value), name);
+        }
         else if (name === '--account-id') {
             filters.accountId = setOnce(filters.accountId, value, name);
         }
@@ -232,6 +237,9 @@ function parseTransactions(args) {
         && filters.endDate < filters.startDate) {
         throw new UsageError('--end-date must not be before --start-date');
     }
+    if (filters.accountRef !== undefined && filters.accountId !== undefined) {
+        throw new UsageError('Use either --account-ref or --account-id, not both');
+    }
     return filters;
 }
 function parseNamedOptions(args, commandLabel, allowed) {
@@ -267,7 +275,7 @@ function requiredOption(values, option, commandLabel) {
     return value;
 }
 function parseAccountRef(value) {
-    if (!/^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value)) {
+    if (!isAccountRef(value)) {
         throw new UsageError('--account-ref must be a valid accountRef from sloth-agent accounts');
     }
     return value;

package/dist/cli.js

@@ -4,7 +4,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.13.0';
+export const CLI_VERSION = '0.14.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -42,7 +42,7 @@ export function usageText() {
         '  sloth-agent line-items rename --scope personal|joint --category-id ID --line-item-id ID --name NAME [--apply]',
         '  sloth-agent transactions [--uncategorized[=true|false]] [--shared[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
-        '    [--account-id ID] [--category-id ID] [--line-item-id ID]',
+        '    [--account-ref REF] [--account-id ID] [--category-id ID] [--line-item-id ID]',
         '    [--cursor CURSOR] [--base-url URL]',
         '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
         '  sloth-agent goals [list] [--base-url URL]',
@@ -547,7 +547,9 @@ export function transactionsHelpText() {
         '  --start-date YYYY-MM-DD        Optional. Include transactions on or after this date.',
         '  --end-date YYYY-MM-DD          Optional. Include transactions on or before this date.',
         '  --q TEXT                       Optional. Search transactions by text.',
-        '  --account-id ID                Optional. Filter by account ID.',
+        '  --account-ref REF              Optional. Filter by the opaque accountRef from sloth-agent accounts.',
+        '                                  Copy the exact sloth_account_v1_... value.',
+        '  --account-id ID                Optional legacy filter by provider or stored account ID.',
         '  --category-id ID               Optional. Filter by category ID.',
         '  --line-item-id ID              Optional. Filter primary or split assignments by line-item ID.',
         '  --assignment-scope SCOPE        Optional. Filter assignments by personal or joint.',
@@ -559,6 +561,7 @@ export function transactionsHelpText() {
         '',
         'Constraints:',
         '  All filters are omitted by default.',
+        '  Use either --account-ref or --account-id, not both.',
         '  --end-date must not be before --start-date.',
         '  The first transaction read each UTC day may refresh linked bank data.',
         '  Refresh remotely persists booked transactions and account balances.',
@@ -566,6 +569,7 @@ export function transactionsHelpText() {
         '',
         'Output:',
         '  JSON containing transactions, nextCursor, and structured refresh status.',
+        '  Every transaction includes accountRef for its originating account.',
         '  Refresh failures do not hide readable cached transactions.',
         '  Personal assignments use the top-level categoryId, lineItemId, and categorySplits.',
         '  Joint assignments appear under jointBudgetContribution.',
@@ -1034,6 +1038,8 @@ function buildTransactionsQuery(filters) {
         params.set('endDate', filters.endDate);
     if (filters.q !== undefined)
         params.set('q', filters.q);
+    if (filters.accountRef !== undefined)
+        params.set('accountRef', filters.accountRef);
     if (filters.accountId !== undefined)
         params.set('accountId', filters.accountId);
     if (filters.categoryId !== undefined)

package/dist/contracts.js

@@ -1,4 +1,5 @@
 import { ApiError, UsageError, } from './errors.js';
+import { isAccountRef } from './account-ref.js';
 import { CATEGORY_TYPES, ICON_KEYS } from './category-metadata.js';
 import { isGoalType } from './goal-metadata.js';
 function isObject(value) {
@@ -252,6 +253,7 @@ function isTransaction(value) {
         && typeof value.currency === 'string'
         && typeof value.date === 'string'
         && value.status === 'booked'
+        && isAccountRef(value.accountRef)
         && typeof value.accountId === 'string'
         && typeof value.accountDocId === 'string'
         && typeof value.requisitionId === 'string'
@@ -621,8 +623,7 @@ function isAccount(value) {
             'connectionState',
             'isGoalSavingsSource',
         ])
-        && typeof value.accountRef === 'string'
-        && /^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value.accountRef)
+        && isAccountRef(value.accountRef)
         && isNullableNonEmptyString(value.accountName)
         && isNullableNonEmptyString(value.institutionName)
         && (value.accountType === 'current'
@@ -659,8 +660,7 @@ function isAccountRemovalResponse(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));
+        && isAccountRef(value.accountRef));
 }
 function isInvestmentHolding(value) {
     return (isObject(value)

package/package.json

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