@slothmoney/agent-cli 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.5.0 - 2026-08-07
+
+- Create and rename custom categories, with existing icon and category type
+  validation and preview-only writes unless `--apply` is supplied.
+- Create and rename personal or joint budget line items while preserving
+  historical snapshots and future plan amounts.
+- Filter transactions directly by `--line-item-id`, including paired
+  `--category-id` matching for split assignments.
+- Strictly validate category and line-item mutation responses and extend
+  command-specific and packed-binary help coverage.
+
+## 0.4.0 - 2026-08-01
+
+- Document that new Sloth Money personal access tokens are view-only by
+  default, and identify the CLI operations that require explicit write access.
+- Add the read-only `sloth-agent accounts` command with strict runtime
+  validation for opaque references, ownership, native balances, sources, and
+  freshness metadata.
+- Prepare 0.4.0 by removing the obsolete `joint-budget-settings` command. Shared
+  personal transactions now enter the joint budget through their assignment.
+- Verify each trusted npm release from a fresh temporary directory so the
+  registry smoke test cannot resolve a repository-local CLI executable.
+
 ## 0.3.1 - 2026-07-31
 
 - Coordinate transaction reads with the Sloth Budget daily refresh process.

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to manage goals and categorise transactions through the
+Use your own agent to inspect known accounts, 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.3.1 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.5.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -24,6 +24,12 @@ 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`,
+`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
+permissions cannot be changed later - revoke and reissue the token instead.
+
 ### Local computer
 
 On an interactive desktop, save the token in your operating system's secure
@@ -96,10 +102,12 @@ options, output, and examples:
 
 ```bash
 sloth-agent auth login --help
+sloth-agent accounts --help
 sloth-agent categories --help
+sloth-agent categories create --help
+sloth-agent line-items create --help
 sloth-agent transactions --help
 sloth-agent assign --help
-sloth-agent joint-budget-settings --help
 sloth-agent goals create --help
 sloth-agent goals update --help
 sloth-agent ask-partner --help
@@ -158,6 +166,8 @@ does not guarantee that applying it will succeed.
 sloth-agent assign --input assignments.json --apply
 ```
 
+This step requires a token created with **Allow changes**.
+
 Inspect every item in the returned `succeeded` and `failed` arrays.
 
 6. Check the result. Successful assignments update the category and optional
@@ -174,6 +184,77 @@ query. Assignments do not create a separate list.
 
 ### Other workflows
 
+Create or rename a custom category. Writes are previews until `--apply` is
+present:
+
+```bash
+sloth-agent categories create \
+  --name "Holidays" \
+  --icon-key plane \
+  --type Wants
+
+sloth-agent categories create \
+  --name "Holidays" \
+  --icon-key plane \
+  --type Wants \
+  --apply
+
+sloth-agent categories rename \
+  --category-id category-id \
+  --name "Travel fund" \
+  --apply
+```
+
+Built-in categories cannot be renamed. A created category is available in the
+next `sloth-agent categories` result without needing a budget allocation.
+
+Create or rename a line item within a personal or joint budget:
+
+```bash
+sloth-agent line-items create \
+  --scope personal \
+  --category-id groceries \
+  --name "Weekly shop" \
+  --apply
+
+sloth-agent line-items rename \
+  --scope personal \
+  --category-id groceries \
+  --line-item-id line-item-id \
+  --name "Essentials" \
+  --apply
+```
+
+Line-item writes update the current period and explicit future plans.
+Historical snapshots remain unchanged. New items start at zero and do not
+change total allocation.
+
+Filter transactions by a line-item ID. Pair it with `--category-id` when the
+same ID may appear under different categories:
+
+```bash
+sloth-agent transactions \
+  --assignment-scope personal \
+  --category-id groceries \
+  --line-item-id line-item-id
+```
+
+The category and line-item IDs must match the same primary assignment or split.
+
+Read the existing Sloth account inventory:
+
+```bash
+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
+`null`; currencies are never converted or combined. Partner personal accounts
+are excluded, while enabled shared joint accounts follow Sloth's existing
+visibility rules.
+
 List your goals:
 
 ```bash
@@ -243,16 +324,13 @@ account failure remains eligible for an automatic retry.
 Set `"assignmentScope": "joint"` on an assignment to categorise the eligible
 shared portion for the joint budget.
 
-Set whether the shared portions of personal-account transactions count in the
-linked joint budget. The first command previews; the second applies:
+Transaction reads expose `personalBudgetAmountPence` for the caller's explicit
+personal-only portion and `jointBudgetContribution.amountPence` for the full
+shared portion. The 60/40 settlement ratio does not reduce joint-budget spend.
 
-```bash
-sloth-agent joint-budget-settings \
-  --include-shared-personal-transactions=true
-sloth-agent joint-budget-settings \
-  --include-shared-personal-transactions=true \
-  --apply
-```
+Shared personal-account transactions with a joint assignment are included in
+the joint budget automatically. The settlement ratio remains independent from
+the amount attributed to the joint budget.
 
 Create a partner clarification link:
 
@@ -296,3 +374,15 @@ npm run verify
 
 `npm run test:package` packs the exact npm artifact, installs it into a clean
 temporary project, and runs the installed binary.
+
+## Releasing
+
+Releases are published only through the trusted `Publish npm release` GitHub
+workflow from a reviewed `v*` tag whose version matches `package.json`. The
+workflow runs the full verification suite before publishing.
+
+After npm accepts the package, the workflow verifies the exact published
+version with `npm run test:registry -- VERSION`. That script runs `npm exec`
+from a fresh temporary directory with an isolated npm cache, so a checkout's
+older local `sloth-agent` executable cannot satisfy the registry smoke test.
+The temporary directory is removed after the check.

package/dist/args.js

@@ -1,4 +1,5 @@
 import { UsageError } from './errors.js';
+import { CATEGORY_TYPES, ICON_KEYS, } from './category-metadata.js';
 const PRODUCTION_BASE_URL = 'https://budget.slothmoney.app';
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 function readOptionValue(args, index, name) {
@@ -88,6 +89,28 @@ function parseGoalId(value) {
     }
     return goalId;
 }
+function parseResourceId(value, option) {
+    const id = value.trim();
+    if (!id
+        || id.length > 500
+        || id.includes('/')
+        || Array.from(id).some((character) => {
+            const codePoint = character.codePointAt(0);
+            return codePoint !== undefined && (codePoint < 32 || codePoint === 127);
+        })) {
+        const resource = option === '--category-id' ? 'category' : 'line-item';
+        throw new UsageError(`${option} must be a valid ${resource} document ID`);
+    }
+    return id;
+}
+function parseResourceName(value) {
+    const name = value.trim();
+    if (!name)
+        throw new UsageError('--name requires a value');
+    if (name.length > 200)
+        throw new UsageError('--name must be at most 200 characters');
+    return name;
+}
 function parseTransactions(args) {
     const filters = {};
     for (let index = 0; index < args.length; index += 1) {
@@ -114,6 +137,7 @@ function parseTransactions(args) {
             '--q',
             '--account-id',
             '--category-id',
+            '--line-item-id',
             '--assignment-scope',
             '--cursor',
         ]);
@@ -150,6 +174,9 @@ function parseTransactions(args) {
         else if (name === '--category-id') {
             filters.categoryId = setOnce(filters.categoryId, value, name);
         }
+        else if (name === '--line-item-id') {
+            filters.lineItemId = setOnce(filters.lineItemId, value, name);
+        }
         else if (name === '--assignment-scope') {
             if (value !== 'personal' && value !== 'joint') {
                 throw new UsageError('--assignment-scope must be personal or joint');
@@ -167,6 +194,105 @@ function parseTransactions(args) {
     }
     return filters;
 }
+function parseNamedOptions(args, commandLabel, allowed) {
+    const values = new Map();
+    let apply = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--apply') {
+            if (apply)
+                throw new UsageError('--apply may only be provided once');
+            apply = true;
+            continue;
+        }
+        const [option, inlineValue] = argument.includes('=')
+            ? argument.split(/=(.*)/s, 2)
+            : [argument, undefined];
+        if (!option || !allowed.has(option)) {
+            throw new UsageError(`Unknown ${commandLabel} option: ${argument}`);
+        }
+        if (values.has(option))
+            throw new UsageError(`${option} may only be provided once`);
+        const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+        if (inlineValue === undefined)
+            index += 1;
+        values.set(option, value);
+    }
+    return { values, apply };
+}
+function requiredOption(values, option, commandLabel) {
+    const value = values.get(option);
+    if (!value)
+        throw new UsageError(`${commandLabel} requires ${option} <value>`);
+    return value;
+}
+function parseCategories(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0)
+            throw new UsageError(`Unknown categories list option: ${args[0]}`);
+        return withBaseUrl({ command: 'categories' }, baseUrl);
+    }
+    if (subcommand === 'create') {
+        const { values, apply } = parseNamedOptions(args, 'categories create', new Set(['--name', '--icon-key', '--type']));
+        const iconKey = requiredOption(values, '--icon-key', 'categories create');
+        const categoryType = requiredOption(values, '--type', 'categories create');
+        if (!ICON_KEYS.includes(iconKey)) {
+            throw new UsageError(`--icon-key must be one of: ${ICON_KEYS.join(', ')}`);
+        }
+        if (!CATEGORY_TYPES.includes(categoryType)) {
+            throw new UsageError(`--type must be one of: ${CATEGORY_TYPES.join(', ')}`);
+        }
+        return withBaseUrl({
+            command: 'categories-create',
+            name: parseResourceName(requiredOption(values, '--name', 'categories create')),
+            iconKey: iconKey,
+            categoryType: categoryType,
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'rename') {
+        const { values, apply } = parseNamedOptions(args, 'categories rename', new Set(['--category-id', '--name']));
+        return withBaseUrl({
+            command: 'categories-rename',
+            categoryId: parseResourceId(requiredOption(values, '--category-id', 'categories rename'), '--category-id'),
+            name: parseResourceName(requiredOption(values, '--name', 'categories rename')),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand.startsWith('-')) {
+        throw new UsageError(`Unknown categories option: ${subcommand}`);
+    }
+    throw new UsageError(`Unknown categories command: ${subcommand}`);
+}
+function parseLineItems(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand !== 'create' && subcommand !== 'rename') {
+        throw new UsageError('line-items requires create or rename');
+    }
+    const allowed = new Set(['--scope', '--category-id', '--name']);
+    if (subcommand === 'rename')
+        allowed.add('--line-item-id');
+    const { values, apply } = parseNamedOptions(args, `line-items ${subcommand}`, allowed);
+    const scope = requiredOption(values, '--scope', `line-items ${subcommand}`);
+    if (scope !== 'personal' && scope !== 'joint') {
+        throw new UsageError('--scope must be personal or joint');
+    }
+    const common = {
+        scope: scope,
+        categoryId: parseResourceId(requiredOption(values, '--category-id', `line-items ${subcommand}`), '--category-id'),
+        name: parseResourceName(requiredOption(values, '--name', `line-items ${subcommand}`)),
+        apply,
+    };
+    if (subcommand === 'create') {
+        return withBaseUrl({ command: 'line-items-create', ...common }, baseUrl);
+    }
+    return withBaseUrl({
+        command: 'line-items-rename',
+        ...common,
+        lineItemId: parseResourceId(requiredOption(values, '--line-item-id', 'line-items rename'), '--line-item-id'),
+    }, baseUrl);
+}
 function withBaseUrl(value, baseUrl) {
     return baseUrl === undefined ? value : { ...value, baseUrl };
 }
@@ -411,10 +537,23 @@ function helpTopic(argv) {
             return 'goals-delete';
         return 'goals';
     }
-    if (command === 'categories'
+    if (command === 'categories') {
+        if (subcommand === 'create')
+            return 'categories-create';
+        if (subcommand === 'rename')
+            return 'categories-rename';
+        return 'categories';
+    }
+    if (command === 'line-items') {
+        if (subcommand === 'create')
+            return 'line-items-create';
+        if (subcommand === 'rename')
+            return 'line-items-rename';
+        return undefined;
+    }
+    if (command === 'accounts'
         || command === 'transactions'
         || command === 'assign'
-        || command === 'joint-budget-settings'
         || command === 'ask-partner') {
         return command;
     }
@@ -438,8 +577,14 @@ export function parseArgs(argv) {
         return parseGoals(args, baseUrl);
     }
     if (command === 'categories') {
+        return parseCategories(args, baseUrl);
+    }
+    if (command === 'line-items') {
+        return parseLineItems(args, baseUrl);
+    }
+    if (command === 'accounts') {
         if (args.length > 0) {
-            throw new UsageError(`Unknown categories option: ${args[0]}`);
+            throw new UsageError(`Unknown accounts option: ${args[0]}`);
         }
         return withBaseUrl({ command }, baseUrl);
     }
@@ -471,43 +616,6 @@ export function parseArgs(argv) {
             throw new UsageError('assign requires --input <file>');
         return withBaseUrl({ command, input, apply }, baseUrl);
     }
-    if (command === 'joint-budget-settings') {
-        let includeSharedPersonalTransactions;
-        let apply = false;
-        for (let index = 0; index < args.length; index += 1) {
-            const argument = args[index];
-            if (argument === '--apply') {
-                if (apply)
-                    throw new UsageError('--apply may only be provided once');
-                apply = true;
-                continue;
-            }
-            const optionName = '--include-shared-personal-transactions';
-            if (argument === optionName || argument.startsWith(`${optionName}=`)) {
-                const value = argument === optionName
-                    ? readOptionValue(args, index, optionName)
-                    : argument.slice(`${optionName}=`.length);
-                if (argument === optionName)
-                    index += 1;
-                if (value !== 'true' && value !== 'false') {
-                    throw new UsageError(`${optionName} must be true or false`);
-                }
-                includeSharedPersonalTransactions = setOnce(includeSharedPersonalTransactions, value === 'true', optionName);
-                continue;
-            }
-            throw new UsageError(`Unknown joint-budget-settings option: ${argument}`);
-        }
-        if (apply && includeSharedPersonalTransactions === undefined) {
-            throw new UsageError('--apply requires --include-shared-personal-transactions=true|false');
-        }
-        return withBaseUrl({
-            command,
-            ...(includeSharedPersonalTransactions === undefined
-                ? {}
-                : { includeSharedPersonalTransactions }),
-            apply,
-        }, baseUrl);
-    }
     if (command === 'ask-partner') {
         let transactionRef;
         for (let index = 0; index < args.length; index += 1) {

package/dist/category-metadata.js

@@ -0,0 +1,11 @@
+export const ICON_KEYS = [
+    'home', 'shopping-cart', 'plane', 'car', 'bill', 'dots', 'chart', 'receipt',
+    'credit-card', 'user', 'utensils', 'truck', 'calendar', 'heart', 'shopping-bag',
+    'gift', 'ban', 'question', 'arrows-sync', 'dollar-sign', 'plus',
+];
+export const CATEGORY_TYPES = [
+    'Needs',
+    'Debts',
+    'Savings & Investments',
+    'Wants',
+];

package/dist/cli.js

@@ -1,9 +1,10 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
-import { parseApiResponse, validateAssignmentPayload, validateJointBudgetSettingsResponse, } from './contracts.js';
+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.3.1';
+export const CLI_VERSION = '0.5.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -24,12 +25,17 @@ 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 categories [--base-url URL]',
+        '  sloth-agent accounts [--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]',
+        '  sloth-agent line-items create --scope personal|joint --category-id ID --name NAME [--apply]',
+        '  sloth-agent line-items rename --scope personal|joint --category-id ID --line-item-id ID --name NAME [--apply]',
         '  sloth-agent transactions [--uncategorized[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
-        '    [--account-id ID] [--category-id ID] [--cursor CURSOR] [--base-url URL]',
+        '    [--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 joint-budget-settings [--include-shared-personal-transactions=true|false] [--apply]',
         '  sloth-agent goals [list] [--base-url URL]',
         '  sloth-agent goals create --name NAME [--target-amount AMOUNT]',
         '    [--target-month YYYY-MM] [--apply] [--base-url URL]',
@@ -51,6 +57,10 @@ export function usageText() {
         'Environment:',
         '  SLOTH_AGENT_TOKEN         Personal access token from Settings > Developer access',
         '  SLOTH_AGENT_API_BASE_URL  Optional API origin; defaults to https://budget.slothmoney.app',
+        '',
+        'Access:',
+        '  New tokens are view-only. Enable Allow changes in Sloth Money when the',
+        '  CLI needs to call write endpoints.',
     ].join('\n');
 }
 export function authHelpText() {
@@ -89,6 +99,8 @@ export function authLoginHelpText() {
         '  Tokens must start with sloth_pat_v1_ and contain no whitespace.',
         '  Never pass a token as a command argument.',
         '  An existing stored credential is replaced only after remote validation succeeds.',
+        '  Remote validation requires agent:read. Commands that write also require',
+        '  agent:write, selected with Allow changes when the token is created.',
         ...API_ORIGIN_HELP_LINES,
         '',
         'Examples:',
@@ -154,7 +166,7 @@ export function categoriesHelpText() {
         'Read categories and the personal and joint line items within them.',
         '',
         'Usage:',
-        '  sloth-agent categories [--base-url URL]',
+        '  sloth-agent categories [list] [--base-url URL]',
         '',
         'Options:',
         '  --base-url URL   Optional. Override the API origin.',
@@ -182,6 +194,110 @@ export function categoriesHelpText() {
         '  jointLineItemsByCategoryId       Joint child line items keyed by category ID',
     ].join('\n');
 }
+export function categoriesCreateHelpText() {
+    return [
+        'Sloth Agent CLI — categories create',
+        '',
+        'Create a custom category.',
+        '',
+        'Usage:',
+        '  sloth-agent categories create --name NAME --icon-key KEY --type TYPE [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --name NAME       Category name, up to 200 characters.',
+        `  --icon-key KEY    One of: ${ICON_KEYS.join(', ')}.`,
+        '  --type TYPE       Needs, Debts, Savings & Investments, or Wants.',
+        '',
+        'Write behavior:',
+        '  Without --apply, returns a JSON preview and makes no mutation request.',
+        '  With --apply, creates the category globally and requires a write-enabled token.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON containing category.id, name, iconKey, categoryType, and source.',
+    ].join('\n');
+}
+export function categoriesRenameHelpText() {
+    return [
+        'Sloth Agent CLI — categories rename',
+        '',
+        'Rename a user-created category. Built-in categories are immutable.',
+        '',
+        'Usage:',
+        '  sloth-agent categories rename --category-id ID --name NAME [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --category-id ID  Custom category document ID.',
+        '  --name NAME        New category name, up to 200 characters.',
+        '',
+        'Write behavior:',
+        '  Without --apply, returns a JSON preview and makes no mutation request.',
+        '  With --apply, renames the canonical category and requires a write-enabled token.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON containing the renamed category.',
+    ].join('\n');
+}
+function lineItemsMutationHelpText(operation) {
+    const rename = operation === 'rename';
+    return [
+        `Sloth Agent CLI — line-items ${operation}`,
+        '',
+        rename ? 'Rename a scoped budget line item.' : 'Create a scoped budget line item at zero.',
+        '',
+        'Usage:',
+        rename
+            ? '  sloth-agent line-items rename --scope personal|joint --category-id ID --line-item-id ID --name NAME [--apply] [--base-url URL]'
+            : '  sloth-agent line-items create --scope personal|joint --category-id ID --name NAME [--apply] [--base-url URL]',
+        '',
+        'Required inputs:',
+        '  --scope SCOPE       personal or joint.',
+        '  --category-id ID    Parent category ID.',
+        ...(rename ? ['  --line-item-id ID   Existing child line-item ID.'] : []),
+        '  --name NAME         Line-item name, up to 200 characters.',
+        '',
+        'Write behavior:',
+        '  Without --apply, returns a JSON preview and makes no mutation request.',
+        '  With --apply, updates the current period and explicit future plans.',
+        '  Historical snapshots remain unchanged. A write-enabled token is required.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON containing scope, categoryId, and lineItem.id and name.',
+    ].join('\n');
+}
+export function lineItemsCreateHelpText() {
+    return lineItemsMutationHelpText('create');
+}
+export function lineItemsRenameHelpText() {
+    return lineItemsMutationHelpText('rename');
+}
+export function accountsHelpText() {
+    return [
+        'Sloth Agent CLI — accounts',
+        '',
+        'Read the existing Sloth account inventory known to the authenticated user.',
+        '',
+        'Usage:',
+        '  sloth-agent accounts [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access:',
+        '  This command is read-only and does not refresh connected accounts.',
+        '',
+        'Output:',
+        '  asOf                   Server response time',
+        '  accounts[].accountRef  Opaque stable account reference',
+        '  accounts[].ownership   personal or joint',
+        '  accounts[].balanceAmount and currency in the native currency when known',
+        '  accounts[].connectionState and lastBalanceUpdatedAt for freshness',
+    ].join('\n');
+}
 export function transactionsHelpText() {
     return [
         'Sloth Agent CLI — transactions',
@@ -199,6 +315,7 @@ export function transactionsHelpText() {
         '  --q TEXT                       Optional. Search transactions by text.',
         '  --account-id ID                Optional. Filter by 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.',
         '  --cursor CURSOR                Optional. Continue from a previous nextCursor.',
         '  --base-url URL                 Optional. Override the API origin.',
@@ -248,6 +365,7 @@ export function assignHelpText() {
         '  A successful preview does not guarantee that applying it will succeed.',
         '  With --apply, assignments are best-effort; any failed item makes the command',
         '  exit with code 1 while the complete result remains available on stdout.',
+        '  Applying requires a write-enabled token created with Allow changes.',
         '',
         'Input:',
         '  The top-level object must contain an assignments array.',
@@ -288,37 +406,6 @@ export function assignHelpText() {
         '  Assignments do not create a separate list.',
     ].join('\n');
 }
-export function jointBudgetSettingsHelpText() {
-    return [
-        'Sloth Agent CLI — joint-budget-settings',
-        '',
-        'Read or update whether shared personal transactions count in the linked joint budget.',
-        '',
-        'Usage:',
-        '  sloth-agent joint-budget-settings [options]',
-        '',
-        'Options:',
-        '  --include-shared-personal-transactions=true|false',
-        '                      Optional. Preview the linked setting change.',
-        '  --apply             Optional. Apply the previewed setting change.',
-        '  --base-url URL      Optional. Override the API origin.',
-        '  -h, --help          Show this help.',
-        ...API_ORIGIN_HELP_LINES,
-        '',
-        'Safety:',
-        '  With no setting option, the command is read-only.',
-        '  Without --apply, a setting option returns a dry-run preview and does not write.',
-        '  --apply requires an explicit true or false setting value.',
-        '',
-        'Examples:',
-        '  sloth-agent joint-budget-settings',
-        '  sloth-agent joint-budget-settings --include-shared-personal-transactions=true',
-        '  sloth-agent joint-budget-settings --include-shared-personal-transactions=true --apply',
-        '',
-        'Output:',
-        '  JSON containing the linked setting, audit metadata, or a dry-run payload.',
-    ].join('\n');
-}
 export function goalsHelpText() {
     return [
         'Sloth Agent CLI — goals',
@@ -379,6 +466,7 @@ export function goalsCreateHelpText() {
         '',
         'Safety:',
         '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Applying requires a write-enabled token created with Allow changes.',
         '  New goals are private to the owner and appended to the existing goal order.',
         '',
         'Example:',
@@ -424,6 +512,7 @@ export function goalsUpdateHelpText() {
         '',
         'Safety:',
         '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Applying requires a write-enabled token created with Allow changes.',
         '',
         'Output:',
         '  Preview mode returns dryRun, method, endpoint, and payload.',
@@ -448,6 +537,7 @@ export function goalsDeleteHelpText() {
         '',
         'Safety:',
         '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Applying requires a write-enabled token created with Allow changes.',
         '  Applying deletion also removes the goal from forecast assignments and',
         '  removes its goal drift history. This operation cannot be undone.',
         '',
@@ -473,6 +563,7 @@ export function askPartnerHelpText() {
         '',
         'Write behavior:',
         '  Running this command creates the request immediately. There is no preview mode.',
+        '  Creating the request requires a write-enabled token created with Allow changes.',
         '',
         'Example:',
         '  sloth-agent ask-partner --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE',
@@ -489,10 +580,14 @@ export function commandHelpText(topic) {
         'auth-login': authLoginHelpText,
         'auth-status': authStatusHelpText,
         'auth-logout': authLogoutHelpText,
+        accounts: accountsHelpText,
         categories: categoriesHelpText,
+        'categories-create': categoriesCreateHelpText,
+        'categories-rename': categoriesRenameHelpText,
+        'line-items-create': lineItemsCreateHelpText,
+        'line-items-rename': lineItemsRenameHelpText,
         transactions: transactionsHelpText,
         assign: assignHelpText,
-        'joint-budget-settings': jointBudgetSettingsHelpText,
         goals: goalsHelpText,
         'goals-list': goalsListHelpText,
         'goals-create': goalsCreateHelpText,
@@ -588,6 +683,8 @@ function buildTransactionsQuery(filters) {
         params.set('accountId', filters.accountId);
     if (filters.categoryId !== undefined)
         params.set('categoryId', filters.categoryId);
+    if (filters.lineItemId !== undefined)
+        params.set('lineItemId', filters.lineItemId);
     if (filters.assignmentScope !== undefined) {
         params.set('assignmentScope', filters.assignmentScope);
     }
@@ -739,6 +836,40 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
+        if (parsed.command === 'categories-create'
+            || parsed.command === 'categories-rename'
+            || parsed.command === 'line-items-create'
+            || parsed.command === 'line-items-rename') {
+            const isCategory = parsed.command.startsWith('categories-');
+            const isCreate = parsed.command.endsWith('-create');
+            const resourceId = parsed.command === 'categories-rename'
+                ? parsed.categoryId
+                : parsed.command === 'line-items-rename'
+                    ? parsed.lineItemId
+                    : null;
+            const endpoint = isCreate
+                ? `${baseUrl}/api/agent/v1/${isCategory ? 'categories' : 'line-items'}`
+                : `${baseUrl}/api/agent/v1/${isCategory ? 'categories' : 'line-items'}/${encodeURIComponent(resourceId)}`;
+            const payload = parsed.command === 'categories-create'
+                ? { name: parsed.name, iconKey: parsed.iconKey, categoryType: parsed.categoryType }
+                : parsed.command === 'categories-rename'
+                    ? { name: parsed.name }
+                    : { scope: parsed.scope, categoryId: parsed.categoryId, name: parsed.name };
+            const method = isCreate ? 'POST' : 'PATCH';
+            if (!parsed.apply) {
+                writeJson(writeStdout, { dryRun: true, endpoint, method, payload });
+                return 0;
+            }
+            const response = await fetchImplementation(endpoint, {
+                method,
+                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 === 'goals-create') {
             const endpoint = `${baseUrl}/api/agent/v1/goals`;
             const payload = {
@@ -847,36 +978,6 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return hasFailures(data) ? 1 : 0;
         }
-        if (parsed.command === 'joint-budget-settings') {
-            const endpoint = `${baseUrl}/api/agent/v1/joint-budget-settings`;
-            if (parsed.includeSharedPersonalTransactions !== undefined && !parsed.apply) {
-                writeJson(writeStdout, {
-                    dryRun: true,
-                    endpoint,
-                    payload: {
-                        includeSharedPersonalTransactions: parsed.includeSharedPersonalTransactions,
-                    },
-                });
-                return 0;
-            }
-            const response = await fetchImplementation(endpoint, {
-                method: parsed.apply ? 'PUT' : 'GET',
-                headers: parsed.apply
-                    ? { ...headers, 'Content-Type': 'application/json' }
-                    : headers,
-                ...(parsed.apply
-                    ? {
-                        body: JSON.stringify({
-                            includeSharedPersonalTransactions: parsed.includeSharedPersonalTransactions,
-                        }),
-                    }
-                    : {}),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-            const data = validateJointBudgetSettingsResponse(await parseHttpResponse(response, token));
-            writeJson(writeStdout, data);
-            return 0;
-        }
         if (parsed.command === 'ask-partner') {
             const response = await fetchImplementation(`${baseUrl}/api/agent/v1/transaction-explanation-requests`, {
                 method: 'POST',
@@ -901,12 +1002,14 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
-        const path = parsed.command === 'categories'
-            ? '/api/agent/v1/categories'
-            : `/api/agent/v1/transactions${(() => {
-                const query = buildTransactionsQuery(parsed.filters);
-                return query ? `?${query}` : '';
-            })()}`;
+        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}` : '';
+                })()}`;
         const response = await fetchImplementation(`${baseUrl}${path}`, {
             method: 'GET',
             headers: parsed.command === 'transactions'

package/dist/contracts.js

@@ -1,4 +1,5 @@
 import { ApiError, UsageError, } from './errors.js';
+import { CATEGORY_TYPES, ICON_KEYS } from './category-metadata.js';
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -128,6 +129,36 @@ function isCategoryResponse(value) {
         && isLineItemMap(value.personalLineItemsByCategoryId)
         && isLineItemMap(value.jointLineItemsByCategoryId));
 }
+function isCategoryMutationResponse(value) {
+    if (!isObject(value) || !hasOnlyFields(value, ['category']) || !isObject(value.category)) {
+        return false;
+    }
+    const category = value.category;
+    return (hasOnlyFields(category, ['id', 'name', 'iconKey', 'categoryType', 'source'])
+        && typeof category.id === 'string'
+        && category.id.trim().length > 0
+        && typeof category.name === 'string'
+        && category.name.trim().length > 0
+        && typeof category.iconKey === 'string'
+        && ICON_KEYS.includes(category.iconKey)
+        && typeof category.categoryType === 'string'
+        && CATEGORY_TYPES.includes(category.categoryType)
+        && category.source === 'user');
+}
+function isLineItemMutationResponse(value) {
+    if (!isObject(value)
+        || !hasOnlyFields(value, ['scope', 'categoryId', 'lineItem'])
+        || (value.scope !== 'personal' && value.scope !== 'joint')
+        || typeof value.categoryId !== 'string'
+        || !value.categoryId.trim()
+        || !isObject(value.lineItem))
+        return false;
+    return (hasOnlyFields(value.lineItem, ['id', 'name'])
+        && typeof value.lineItem.id === 'string'
+        && value.lineItem.id.trim().length > 0
+        && typeof value.lineItem.name === 'string'
+        && value.lineItem.name.trim().length > 0);
+}
 function isTransaction(value) {
     return (isObject(value)
         && typeof value.transactionRef === 'string'
@@ -145,6 +176,8 @@ function isTransaction(value) {
         && (value.categoryId === null || typeof value.categoryId === 'string')
         && (value.lineItemId === null || typeof value.lineItemId === 'string')
         && Array.isArray(value.categorySplits)
+        && Number.isInteger(value.personalBudgetAmountPence)
+        && Number(value.personalBudgetAmountPence) >= 0
         && (value.jointBudgetContribution === null
             || (isObject(value.jointBudgetContribution)
                 && typeof value.jointBudgetContribution.eligible === 'boolean'
@@ -197,20 +230,6 @@ function isAssignmentResponse(value) {
             && typeof item.error === 'string'
             && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
 }
-export function validateJointBudgetSettingsResponse(value) {
-    if (!isObject(value)
-        || Object.keys(value).some((key) => !new Set([
-            'includeSharedPersonalTransactions',
-            'updatedAt',
-            'updatedBy',
-        ]).has(key))
-        || typeof value.includeSharedPersonalTransactions !== 'boolean'
-        || (value.updatedAt !== null && !isIsoDateTime(value.updatedAt))
-        || (value.updatedBy !== null && typeof value.updatedBy !== 'string')) {
-        throw new ApiError('Invalid joint budget settings response from the Agent API');
-    }
-    return value;
-}
 function isHttpUrl(value) {
     if (typeof value !== 'string')
         return false;
@@ -266,6 +285,51 @@ function isGoal(value) {
 function isCurrency(value) {
     return typeof value === 'string' && /^[A-Z]{3}$/.test(value);
 }
+function isNullableNonEmptyString(value) {
+    return value === null || (typeof value === 'string'
+        && value.length > 0
+        && value === value.trim());
+}
+function isAccount(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, [
+            'accountRef',
+            'accountName',
+            'institutionName',
+            'accountType',
+            'ownership',
+            'balanceAmount',
+            'currency',
+            'source',
+            'lastBalanceUpdatedAt',
+            'connectionState',
+        ])
+        && typeof value.accountRef === 'string'
+        && /^sloth_account_v1_[A-Za-z0-9_-]{43}$/.test(value.accountRef)
+        && isNullableNonEmptyString(value.accountName)
+        && isNullableNonEmptyString(value.institutionName)
+        && (value.accountType === 'current'
+            || value.accountType === 'savings'
+            || value.accountType === 'investments')
+        && (value.ownership === 'personal' || value.ownership === 'joint')
+        && (value.balanceAmount === null
+            || (typeof value.balanceAmount === 'number' && Number.isFinite(value.balanceAmount)))
+        && (value.currency === null || isCurrency(value.currency))
+        && (value.source === 'connected' || value.source === 'manual')
+        && (value.lastBalanceUpdatedAt === null
+            || isIsoDateTime(value.lastBalanceUpdatedAt))
+        && (value.connectionState === 'active'
+            || value.connectionState === 'expired'
+            || value.connectionState === 'manual'
+            || value.connectionState === 'unknown'));
+}
+function isAccountsResponse(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['asOf', 'accounts'])
+        && isIsoDateTime(value.asOf)
+        && Array.isArray(value.accounts)
+        && value.accounts.every(isAccount));
+}
 function isGoalsResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, ['currency', 'goals'])
@@ -287,19 +351,25 @@ function isGoalDeleteResponse(value) {
         && value.deletedGoalId.trim().length > 0);
 }
 export function parseApiResponse(command, value) {
-    const valid = command === 'categories'
-        ? isCategoryResponse(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);
+    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);
     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.3.1",
+  "version": "0.5.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "prepack": "npm run build",
     "test": "vitest run",
     "test:package": "node scripts/test-package.mjs",
+    "test:registry": "node scripts/test-registry-package.mjs",
     "typecheck": "tsc --noEmit",
     "verify": "npm run lint && npm run typecheck && npm test && npm run build && npm run test:package"
   },