@slothmoney/agent-cli 0.2.0 → 0.3.0

package/dist/cli.js

@@ -1,15 +1,26 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
-import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, validateJointBudgetSettingsResponse, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.2.0';
+export const CLI_VERSION = '0.3.0';
 const REQUEST_TIMEOUT_MS = 30_000;
+const API_ORIGIN_HELP_LINES = [
+    '',
+    'API origin:',
+    '  --base-url overrides SLOTH_AGENT_API_BASE_URL; if neither is set, the',
+    '  origin defaults to https://budget.slothmoney.app.',
+    '  Use an origin-only URL with no credentials, path, query, or fragment.',
+    '  HTTPS is required except for localhost development.',
+];
 export function usageText() {
     return [
         'Sloth Agent CLI',
         '',
         'Usage:',
+        '  sloth-agent <command> [options]',
+        '',
+        'Commands:',
         '  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]',
@@ -18,15 +29,475 @@ export function usageText() {
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
         '    [--account-id ID] [--category-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]',
+        '  sloth-agent goals update --goal-id ID [fields] [--apply] [--base-url URL]',
+        '  sloth-agent goals delete --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
-        '  sloth-agent --help',
-        '  sloth-agent --version',
+        '',
+        'Help:',
+        '  Run sloth-agent <command> --help for options, inputs, output, and examples.',
+        '  Auth and goal subcommands also have help, for example:',
+        '  sloth-agent auth login --help',
+        '  sloth-agent goals update --help',
+        '',
+        'Global options:',
+        '  -h, --help       Show top-level or command-specific help',
+        '  -V, --version    Show the CLI version',
+        '  --base-url URL   Use a different API origin',
         '',
         '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',
     ].join('\n');
 }
+export function authHelpText() {
+    return [
+        'Sloth Agent CLI — auth',
+        '',
+        'Manage the personal access token used for Agent API requests.',
+        '',
+        'Commands:',
+        '  sloth-agent auth login     Validate and store a personal access token',
+        '  sloth-agent auth status    Check the active credential with a live API request',
+        '  sloth-agent auth logout    Remove the token from the native credential store',
+        '',
+        'Help:',
+        '  Run sloth-agent auth <command> --help for command-specific details.',
+    ].join('\n');
+}
+export function authLoginHelpText() {
+    return [
+        'Sloth Agent CLI — auth login',
+        '',
+        'Validate a personal access token, then store it in the native credential store.',
+        '',
+        'Usage:',
+        '  sloth-agent auth login [--token-stdin | --from-env] [--base-url URL]',
+        '',
+        'Options:',
+        '  --token-stdin    Optional. Read the token from stdin.',
+        '  --from-env       Optional. Read the token from SLOTH_AGENT_TOKEN.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Input:',
+        '  With no input option, login uses a hidden prompt and requires an interactive TTY.',
+        '  --token-stdin and --from-env are mutually exclusive.',
+        '  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.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Examples:',
+        '  sloth-agent auth login',
+        '  sloth-agent auth login --token-stdin',
+        '  sloth-agent auth login --from-env',
+        '',
+        'Output:',
+        '  JSON describing the API origin, stored state, and active credential source.',
+    ].join('\n');
+}
+export function authStatusHelpText() {
+    return [
+        'Sloth Agent CLI — auth status',
+        '',
+        'Check the active credential with a live API request.',
+        '',
+        'Usage:',
+        '  sloth-agent auth status [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Example:',
+        '  sloth-agent auth status',
+        '',
+        'Output:',
+        '  JSON containing origin, source, a masked token suffix, and remoteStatus.',
+        '  Checking status updates the token last-used time.',
+    ].join('\n');
+}
+export function authLogoutHelpText() {
+    return [
+        'Sloth Agent CLI — auth logout',
+        '',
+        'Remove the token for an API origin from the native credential store.',
+        '',
+        'Usage:',
+        '  sloth-agent auth logout [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Important:',
+        '  Logout does not revoke the token remotely or unset SLOTH_AGENT_TOKEN.',
+        '  Revoke the token in Sloth Money Settings > Developer access.',
+        '',
+        'Example:',
+        '  sloth-agent auth logout',
+        '',
+        'Output:',
+        '  JSON describing local removal, any environment override, and revocation state.',
+    ].join('\n');
+}
+export function categoriesHelpText() {
+    return [
+        'Sloth Agent CLI — categories',
+        '',
+        'Read categories and the personal and joint line items within them.',
+        '',
+        'Usage:',
+        '  sloth-agent categories [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Budget taxonomy:',
+        '  A category is the broader parent.',
+        '  A line item is a child within one category.',
+        '  Line-item names such as "Other" may repeat. Preserve the full choice as',
+        '  (scope, categoryId, lineItemId), using the personal or joint line-item',
+        '  map matching the transaction scope.',
+        '',
+        'Examples:',
+        '  sloth-agent categories',
+        '  Bills → Other',
+        '  Subscriptions → Other',
+        '',
+        'Access:',
+        '  This command is read-only.',
+        '',
+        'Output:',
+        '  categories                       Parent categories',
+        '  personalLineItemsByCategoryId    Personal child line items keyed by category ID',
+        '  jointLineItemsByCategoryId       Joint child line items keyed by category ID',
+    ].join('\n');
+}
+export function transactionsHelpText() {
+    return [
+        'Sloth Agent CLI — transactions',
+        '',
+        'Read transactions, optionally filtered or paginated.',
+        '',
+        'Usage:',
+        '  sloth-agent transactions [options]',
+        '',
+        'Options:',
+        '  --uncategorized[=true|false]  Optional. Filter by state; with no value, use true.',
+        '  --limit N                     Optional. Integer from 1 to 200; omit for API default.',
+        '  --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.',
+        '  --category-id ID               Optional. Filter by category 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.',
+        '  -h, --help                     Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Constraints:',
+        '  All filters are omitted by default.',
+        '  --end-date must not be before --start-date.',
+        '  This command is read-only.',
+        '',
+        'Output:',
+        '  JSON containing transactions and nextCursor. Use nextCursor with --cursor',
+        '  to request the next page. A null nextCursor means there are no more pages.',
+        '',
+        'Examples:',
+        '  sloth-agent transactions --uncategorized --limit 50',
+        '  sloth-agent transactions --assignment-scope joint --uncategorized',
+        '  sloth-agent transactions --q "tesco" --start-date 2026-05-01 --end-date 2026-05-31',
+    ].join('\n');
+}
+export function assignHelpText() {
+    return [
+        'Sloth Agent CLI — assign',
+        '',
+        'An assignment categorises an existing transaction e.g. assigning category Groceries to a transaction.',
+        'Validate, preview, or apply category assignments from a JSON file.',
+        '',
+        'Usage:',
+        '  sloth-agent assign --input FILE [--apply] [--base-url URL]',
+        '',
+        'Options:',
+        '  --input FILE      Required. JSON assignment file containing 1 to 100 assignments.',
+        '  --apply           Optional. Write assignments to Sloth Money.',
+        '  --base-url URL    Optional. Override the API origin.',
+        '  -h, --help        Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Safety:',
+        '  Without --apply, the command checks that the file is valid and returns',
+        '  the payload it would send. It does not contact Sloth Money, verify the',
+        '  transactionRef or category values, or write anything.',
+        '  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.',
+        '',
+        'Input:',
+        '  The top-level object must contain an assignments array.',
+        '  Each assignment requires transactionRef and a categoryId or non-empty categorySplits.',
+        '  Copy the exact transactionRef from transactions output and categoryId from',
+        '  categories output. The example values below are placeholders.',
+        '  Set categoryId to null to clear an assignment.',
+        '  lineItemId is optional and accepts a non-empty string or null.',
+        '  categorySplits is optional and accepts a non-empty array or null.',
+        '  Each split requires categoryId and a positive integer amountPence;',
+        '  a split lineItemId is optional.',
+        '  incomeSubtype is optional and accepts "pay", "interest", or null.',
+        '  assignmentScope is optional and accepts "personal" or "joint".',
+        '',
+        'Workflow:',
+        '  sloth-agent categories',
+        '  sloth-agent transactions --uncategorized --limit 50',
+        '  sloth-agent assign --input assignments.json          Preview only',
+        '  sloth-agent assign --input assignments.json --apply  Write assignments',
+        '  sloth-agent transactions --limit 50                  Read back the result',
+        '',
+        'Example:',
+        '  {',
+        '    "assignments": [',
+        '      {',
+        '        "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",',
+        '        "categoryId": "PASTE_A_CATEGORY_ID_HERE"',
+        '      }',
+        '    ]',
+        '  }',
+        '  These are placeholders. Replace both values with exact IDs from CLI output.',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, endpoint, and the validated payload.',
+        '  Apply mode returns succeeded and failed assignment arrays.',
+        '  Successful assignments update the original transaction. See the result in',
+        '  Sloth Money → Transactions or read the transaction again through the CLI.',
+        '  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',
+        '',
+        'List, create, update, or delete your savings goals.',
+        '',
+        'Commands:',
+        '  sloth-agent goals list      List goals; "sloth-agent goals" is equivalent.',
+        '  sloth-agent goals create    Preview or create a goal.',
+        '  sloth-agent goals update    Preview or update selected goal fields.',
+        '  sloth-agent goals delete    Preview or permanently delete a goal.',
+        '',
+        'Help:',
+        '  Run sloth-agent goals <command> --help for command-specific details.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function goalsListHelpText() {
+    return [
+        'Sloth Agent CLI — goals list',
+        '',
+        'List your goals in their display order.',
+        '',
+        'Usage:',
+        '  sloth-agent goals [list] [--base-url URL]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Constraints:',
+        '  No filters or singular get are supported.',
+        '  This command is read-only.',
+        '',
+        'Output:',
+        '  JSON containing currency and goals. Each goal contains id, name,',
+        '  targetAmount, targetMonthKey, isAchieved, and sharedWithPartner.',
+    ].join('\n');
+}
+export function goalsCreateHelpText() {
+    return [
+        'Sloth Agent CLI — goals create',
+        '',
+        'Preview or create a goal.',
+        '',
+        'Usage:',
+        '  sloth-agent goals create --name NAME [options]',
+        '',
+        'Options:',
+        '  --name NAME                 Required. Goal name, 1 to 200 characters.',
+        '  --target-amount AMOUNT      Optional. Positive major-unit amount with up to 2 decimals.',
+        '  --target-month YYYY-MM      Optional. Target calendar month.',
+        '  --apply                     Optional. Create the goal in Sloth Money.',
+        '  --base-url URL              Optional. Override the API origin.',
+        '  -h, --help                  Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Safety:',
+        '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  New goals are private to the owner and appended to the existing goal order.',
+        '',
+        'Example:',
+        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000',
+        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --apply',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, endpoint, and payload.',
+        '  Apply mode returns the persisted goal and currency from the 201 response.',
+    ].join('\n');
+}
+export function goalsUpdateHelpText() {
+    return [
+        'Sloth Agent CLI — goals update',
+        '',
+        'Preview or partially update a goal.',
+        '',
+        'Usage:',
+        '  sloth-agent goals update --goal-id ID [fields] [--apply] [--base-url URL]',
+        '',
+        'Options:',
+        '  --goal-id ID                 Required. Goal ID from goals list or create output.',
+        '  --name NAME                  Optional. Replacement name, 1 to 200 characters.',
+        '  --target-amount AMOUNT       Optional. Positive amount with up to 2 decimals.',
+        '  --clear-target-amount        Optional. Remove the target amount.',
+        '  --target-month YYYY-MM       Optional. Replace the target month.',
+        '  --clear-target-month         Optional. Remove the target month.',
+        '  --achieved=true|false        Optional. Mark the goal achieved or active.',
+        '  --apply                      Optional. Write the partial update.',
+        '  --base-url URL               Optional. Override the API origin.',
+        '  -h, --help                   Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Constraints:',
+        '  Provide at least one field to update.',
+        '  Set and clear options for the same field are mutually exclusive.',
+        '  Marking a goal achieved removes its forecast assignment.',
+        '  Marking it active again does not restore the previous assignment.',
+        '  Change active shared pot target amounts in the Sloth Budget app, where',
+        '  account balances can be reconciled across goals in priority order.',
+        '  Sharing remains app-managed. Updates to an already shared goal remain visible',
+        '  to the connected partner.',
+        '',
+        'Safety:',
+        '  Without --apply, the command returns a dry-run preview and does not write.',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, endpoint, and payload.',
+        '  Apply mode returns the complete persisted goal and currency.',
+    ].join('\n');
+}
+export function goalsDeleteHelpText() {
+    return [
+        'Sloth Agent CLI — goals delete',
+        '',
+        'Preview or permanently delete a goal.',
+        '',
+        'Usage:',
+        '  sloth-agent goals delete --goal-id ID [--apply] [--base-url URL]',
+        '',
+        'Options:',
+        '  --goal-id ID    Required. Goal ID from goals list or create output.',
+        '  --apply         Optional. Permanently delete the goal.',
+        '  --base-url URL  Optional. Override the API origin.',
+        '  -h, --help      Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Safety:',
+        '  Without --apply, the command returns a dry-run preview and does not write.',
+        '  Applying deletion also removes the goal from forecast assignments and',
+        '  removes its goal drift history. This operation cannot be undone.',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, and endpoint.',
+        '  Apply mode returns deleted and deletedGoalId.',
+    ].join('\n');
+}
+export function askPartnerHelpText() {
+    return [
+        'Sloth Agent CLI — ask-partner',
+        '',
+        'Create a shareable link asking a partner to clarify a transaction.',
+        '',
+        'Usage:',
+        '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
+        '',
+        'Options:',
+        '  --transaction-ref REF   Required. Stable transactionRef from transaction output.',
+        '  --base-url URL          Optional. Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Write behavior:',
+        '  Running this command creates the request immediately. There is no preview mode.',
+        '',
+        'Example:',
+        '  sloth-agent ask-partner --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE',
+        '  The value shown is a placeholder. Copy the exact transactionRef from',
+        '  sloth-agent transactions output.',
+        '',
+        'Output:',
+        '  JSON containing requestId, publicUrl, message, expiresAt, and status.',
+    ].join('\n');
+}
+export function commandHelpText(topic) {
+    const helpByTopic = {
+        auth: authHelpText,
+        'auth-login': authLoginHelpText,
+        'auth-status': authStatusHelpText,
+        'auth-logout': authLogoutHelpText,
+        categories: categoriesHelpText,
+        transactions: transactionsHelpText,
+        assign: assignHelpText,
+        'joint-budget-settings': jointBudgetSettingsHelpText,
+        goals: goalsHelpText,
+        'goals-list': goalsListHelpText,
+        'goals-create': goalsCreateHelpText,
+        'goals-update': goalsUpdateHelpText,
+        'goals-delete': goalsDeleteHelpText,
+        'ask-partner': askPartnerHelpText,
+    };
+    return helpByTopic[topic]();
+}
 function writeJson(write, data) {
     write(`${JSON.stringify(data, null, 2)}\n`);
 }
@@ -113,6 +584,9 @@ function buildTransactionsQuery(filters) {
         params.set('accountId', filters.accountId);
     if (filters.categoryId !== undefined)
         params.set('categoryId', filters.categoryId);
+    if (filters.assignmentScope !== undefined) {
+        params.set('assignmentScope', filters.assignmentScope);
+    }
     if (filters.cursor !== undefined)
         params.set('cursor', filters.cursor);
     return params.toString();
@@ -188,7 +662,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     try {
         const parsed = parseArgs(argv);
         if (parsed.command === 'help') {
-            writeStdout(`${usageText()}\n`);
+            writeStdout(`${parsed.topic ? commandHelpText(parsed.topic) : usageText()}\n`);
             return 0;
         }
         if (parsed.command === 'version') {
@@ -261,6 +735,94 @@ 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 === 'goals-create') {
+            const endpoint = `${baseUrl}/api/agent/v1/goals`;
+            const payload = {
+                name: parsed.name,
+                ...(parsed.targetAmount === undefined
+                    ? {}
+                    : { targetAmount: parsed.targetAmount }),
+                ...(parsed.targetMonthKey === undefined
+                    ? {}
+                    : { targetMonthKey: parsed.targetMonthKey }),
+            };
+            if (!parsed.apply) {
+                writeJson(writeStdout, {
+                    dryRun: true,
+                    endpoint,
+                    method: 'POST',
+                    payload,
+                });
+                return 0;
+            }
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: {
+                    ...headers,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('goals-create', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'goals-update') {
+            const endpoint = `${baseUrl}/api/agent/v1/goals/${encodeURIComponent(parsed.goalId)}`;
+            const payload = {
+                ...(parsed.name === undefined ? {} : { name: parsed.name }),
+                ...(parsed.targetAmount === undefined
+                    ? {}
+                    : { targetAmount: parsed.targetAmount }),
+                ...(parsed.targetMonthKey === undefined
+                    ? {}
+                    : { targetMonthKey: parsed.targetMonthKey }),
+                ...(parsed.isAchieved === undefined
+                    ? {}
+                    : { isAchieved: parsed.isAchieved }),
+            };
+            if (!parsed.apply) {
+                writeJson(writeStdout, {
+                    dryRun: true,
+                    endpoint,
+                    method: 'PATCH',
+                    payload,
+                });
+                return 0;
+            }
+            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('goals-update', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'goals-delete') {
+            const endpoint = `${baseUrl}/api/agent/v1/goals/${encodeURIComponent(parsed.goalId)}`;
+            if (!parsed.apply) {
+                writeJson(writeStdout, {
+                    dryRun: true,
+                    endpoint,
+                    method: 'DELETE',
+                });
+                return 0;
+            }
+            const response = await fetchImplementation(endpoint, {
+                method: 'DELETE',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('goals-delete', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         if (parsed.command === 'assign') {
             const payload = validateAssignmentPayload(readAssignmentFile(parsed.input));
             const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
@@ -281,6 +843,36 @@ 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',
@@ -295,6 +887,16 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'goals-list') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/goals`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('goals-list', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         const path = parsed.command === 'categories'
             ? '/api/agent/v1/categories'
             : `/api/agent/v1/transactions${(() => {