@slothmoney/agent-cli 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.14.1 - 2026-08-21
+
+- Make every parent help page list its nested commands, and give
+  `line-items --help` its own group page instead of generic top-level usage.
+
+## 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.1 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -98,7 +98,7 @@ An assignment can change an owned transaction's sharing, categorisation, or
 both.
 
 Every command has built-in reference documentation covering its inputs,
-options, output, and examples:
+options, output, and examples. For example:
 
 ```bash
 sloth-agent auth login --help
@@ -109,6 +109,7 @@ sloth-agent budget update --help
 sloth-agent budget move --help
 sloth-agent categories --help
 sloth-agent categories create --help
+sloth-agent line-items --help
 sloth-agent line-items create --help
 sloth-agent transactions --help
 sloth-agent assign --help
@@ -471,6 +472,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;
@@ -795,7 +803,7 @@ function helpTopic(argv) {
             return 'line-items-create';
         if (subcommand === 'rename')
             return 'line-items-rename';
-        return undefined;
+        return 'line-items';
     }
     if (command === 'budget') {
         if (subcommand === 'status')

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.1';
 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]',
@@ -56,7 +56,7 @@ export function usageText() {
         '',
         'Help:',
         '  Run sloth-agent <command> --help for options, inputs, output, and examples.',
-        '  Auth and goal subcommands also have help, for example:',
+        '  Every nested subcommand has its own help, for example:',
         '  sloth-agent auth login --help',
         '  sloth-agent goals update --help',
         '',
@@ -176,6 +176,14 @@ export function categoriesHelpText() {
         '',
         'Read categories and the personal and joint line items within them.',
         '',
+        'Commands:',
+        '  sloth-agent categories list    List categories; "sloth-agent categories" is equivalent.',
+        '  sloth-agent categories create  Preview or create a custom category.',
+        '  sloth-agent categories rename  Preview or rename a custom category.',
+        '',
+        'Help:',
+        '  Run sloth-agent categories <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent categories [list] [--base-url URL]',
         '',
@@ -286,12 +294,35 @@ export function lineItemsCreateHelpText() {
 export function lineItemsRenameHelpText() {
     return lineItemsMutationHelpText('rename');
 }
+export function lineItemsHelpText() {
+    return [
+        'Sloth Agent CLI — line-items',
+        '',
+        'Create or rename personal or joint budget line items.',
+        '',
+        'Commands:',
+        '  sloth-agent line-items create  Preview or create a scoped line item.',
+        '  sloth-agent line-items rename  Preview or rename a scoped line item.',
+        '',
+        'Help:',
+        '  Run sloth-agent line-items <command> --help for command-specific details.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function accountsHelpText() {
     return [
         'Sloth Agent CLI — accounts',
         '',
         'Read the existing Sloth account inventory known to the authenticated user.',
         '',
+        'Commands:',
+        '  sloth-agent accounts list    List accounts; "sloth-agent accounts" is equivalent.',
+        '  sloth-agent accounts update  Preview or update an owned account.',
+        '  sloth-agent accounts remove  Preview or archive an owned manual account.',
+        '',
+        'Help:',
+        '  Run sloth-agent accounts <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent accounts [list] [--base-url URL]',
         '',
@@ -402,6 +433,15 @@ export function budgetHelpText() {
         '',
         'Read one personal or joint budget period.',
         '',
+        'Commands:',
+        '  sloth-agent budget         Read one budget period.',
+        '  sloth-agent budget status  Read assigned, spent, and available money.',
+        '  sloth-agent budget update  Preview or update planned line-item amounts.',
+        '  sloth-agent budget move    Preview or move assigned money.',
+        '',
+        'Help:',
+        '  Run sloth-agent budget <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '',
@@ -547,7 +587,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 +601,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 +609,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.',
@@ -909,6 +953,7 @@ export function commandHelpText(topic) {
         categories: categoriesHelpText,
         'categories-create': categoriesCreateHelpText,
         'categories-rename': categoriesRenameHelpText,
+        'line-items': lineItemsHelpText,
         'line-items-create': lineItemsCreateHelpText,
         'line-items-rename': lineItemsRenameHelpText,
         transactions: transactionsHelpText,
@@ -1034,6 +1079,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.1",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {