Sloth Agent CLI

Use your own agent to inspect personal and household accounts, investments, budgets, pending card activity, and partner settlement context; manage goals and forecast scenarios; move assigned budget money; update planned amounts; categorise booked transactions; and configure payment notifications through the Sloth Money Agent API.

Install

The CLI requires Node.js 22 or newer.

npm install --global @slothmoney/agent-cli
sloth-agent --version

For a one-off pinned run:

npm exec --yes --package=@slothmoney/[email protected] -- sloth-agent --help

Authenticate

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, investments, portfolio, budget, categories, transactions, partner status, goals, and scenarios list. Enable Allow changes when creating the token only if the CLI must apply assignments, manage categories or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals and scenarios. 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 credential store:

sloth-agent auth login

The prompt hides the token. The CLI validates it before replacing any credential already stored for the selected API origin.

Containers, CI, and headless systems

Native credential storage may be unavailable in a container or other headless environment. Inject SLOTH_AGENT_TOKEN at runtime through your platform's secret manager:

export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
sloth-agent auth status

Keep using the environment variable for later commands. You do not need to run sloth-agent auth login in this setup. Do not put the token in a command argument, source file, or container image.

SLOTH_AGENT_TOKEN always overrides a stored credential.

Import an existing environment token

To save an environment token in native credential storage on a local computer:

sloth-agent auth login --from-env
unset SLOTH_AGENT_TOKEN

You can also pass a token to the login command through stdin:

printf '%s' "$SLOTH_AGENT_TOKEN" | sloth-agent auth login --token-stdin

Both commands validate the token before replacing the stored credential.

Check the active credential and read your categories:

sloth-agent auth status
sloth-agent categories

This updates the PAT's lastUsedAt value. To remove the local credential:

sloth-agent auth logout

Logout does not unset SLOTH_AGENT_TOKEN or revoke the PAT. Revoke a PAT remotely in Sloth Money Settings > Developer access.

Commands

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. For example:

sloth-agent auth login --help
sloth-agent accounts --help
sloth-agent portfolio --help
sloth-agent budget --help
sloth-agent budget status --help
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 partner --help
sloth-agent partner status --help
sloth-agent rules --help
sloth-agent assign --help
sloth-agent receipts --help
sloth-agent receipts extract --help
sloth-agent receipts attach --help
sloth-agent goals create --help
sloth-agent goals update --help
sloth-agent goals mark-spent --help
sloth-agent goals restore --help
sloth-agent scenarios create --help
sloth-agent scenarios update --help
sloth-agent scenarios activate --help
sloth-agent ask-partner --help

Add a transaction notification rule

Rules watch future payments that match an existing transaction. They can alert you when the amount changes or before a renewal date. They do not create transactions or recurring predictions.

First, run sloth-agent transactions and copy the exact transactionRef into rule.json alongside this rule definition:

{
  "amountChange": {
    "enabled": true,
    "comparison": "increase",
    "baselinePence": 3184
  },
  "renewalReminder": {
    "enabled": true,
    "renewalDate": "2027-07-30",
    "leadDays": 30
  },
  "delivery": {
    "email": true
  }
}

Set delivery.email to true to receive reminders by email. leadDays accepts an integer from 1 to 365.

Preview the write locally, then apply the same validated file:

sloth-agent rules set \
  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
  --input rule.json

sloth-agent rules set \
  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
  --input rule.json \
  --apply

To extract a renewal date first, scan a PDF no larger than 6 MB:

sloth-agent rules scan-contract --contract contract.pdf --apply

The PDF is discarded after extraction and is not stored. Scanning only returns the date and confidence; use rules set to save the resulting reminder.

Attach receipt items end to end

Receipt items are evidence attached to a booked transaction. They do not change its category, sharing, partner balance, or budget treatment.

1. Copy the exact transactionRef from sloth-agent transactions, then extract a transient draft from a JPEG, PNG, or WebP image up to 8 MB:

sloth-agent receipts extract --image /path/to/receipt.jpg > receipt-draft.json

The image and draft are not saved by Sloth. Review the JSON, remove the outer draft key and warnings, and keep schemaVersion, currency, and the reviewed receiptItems in receipt.json. Each item contains only id, label, and a signed integer amountPence. Purchases and added charges are positive; discounts are negative. Do not add tax already included in other prices as a separate row because the signed rows should sum to the printed receipt total.

2. Preview the exact write without contacting the API:

sloth-agent receipts attach \
  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
  --input receipt.json

3. Apply the reviewed JSON with a write-enabled token:

sloth-agent receipts attach \
  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
  --input receipt.json \
  --apply

Use sloth-agent receipts get --transaction-ref REF to read the saved revision. Pass --expected-revision N when replacing it, or use sloth-agent receipts remove --transaction-ref REF --revision N --apply to remove it.

How transaction categorisation is represented

Personal and joint category assignments are separate. A personal assignment uses the transaction's top-level categoryId, lineItemId, and categorySplits. A joint-budget assignment uses the corresponding fields under jointBudgetContribution.

A transaction can have no personal category while its joint-budget contribution already has a category and line item. To assess a transaction's categorisation, inspect both locations. An included joint contribution with a category and line item is already categorised for the joint budget. For example:

{
  "categoryId": null,
  "lineItemId": null,
  "jointBudgetContribution": {
    "included": true,
    "categoryId": "groceries",
    "lineItemId": "joint-groceries"
  }
}

This transaction is uncategorised personally but categorised as Groceries for the joint budget. The --uncategorized filter applies to the selected assignment scope; the transaction's native scope is used when --assignment-scope is omitted.

Categorise a transaction end to end

1. Read categories and available budget line items:

sloth-agent categories

A category is the broader parent. A line item is a child within one category. Line-item names such as Other may repeat, so preserve the full choice as (scope, categoryId, lineItemId). Use the personal or joint line-item map that matches the transaction scope. For example, Bills → Other and Subscriptions → Other are different choices. Choose the most specific suitable line item; if none fits, use that category's Other line item. Historical assignments without a line item should not be treated as a recommendation to omit one.

2. Read uncategorised transactions:

sloth-agent transactions \
  --assignment-scope personal \
  --uncategorized \
  --limit 50

To read uncategorised joint-budget contributions instead:

sloth-agent transactions \
  --assignment-scope joint \
  --uncategorized \
  --limit 50

The remaining example continues with a personal assignment. For a joint assignment, set "assignmentScope": "joint" in the assignment payload and use --assignment-scope joint when checking the result.

3. Copy the exact transactionRef, categoryId, and lineItemId from the earlier outputs into assignments.json:

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "assignmentScope": "personal",
      "categoryId": "PASTE_A_CATEGORY_ID_HERE",
      "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"
    }
  ]
}

These are placeholders. Do not submit the example values.

Each transactionRef may appear only once in an assignment file. Split one transaction across categories with categorySplits instead of adding the same transaction twice.

4. Preview the assignment without writing:

For Income → Pay, add "incomePeriodKey": "2026-09" to the assignment to fund September with a payment received in August. The bank date stays unchanged. Omission keeps a saved choice; a new Pay assignment defaults to its transaction period. Past periods need saved budget context. Future income stays reserved until its selected period, using unlinked Fund ahead money first. A correction can leave To assign negative. Interest and custom income items cannot use this picker. The CLI's dry run validates the file only; it does not calculate the financial consequence.

{"assignments":[{"transactionRef":"PASTE_THE_EXACT_TRANSACTION_REF_HERE","categoryId":"income","lineItemId":"__sloth_income_pay__","incomePeriodKey":"2026-09"}]}

sloth-agent assign --input assignments.json

Without --apply, the CLI 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.

5. Apply the same file:

sloth-agent assign --input assignments.json --apply

This step requires a token created with Allow changes.

The CLI submits a durable server operation and polls its authenticated status until every item has finished. It then prints the same succeeded and failed arrays as before, so existing agent workflows do not need to change. Inspect every item in both arrays.

If the command is interrupted or a request times out, re-run the same command with the same assignment input. The CLI derives the same request key from the validated assignments, so the server resumes the existing operation instead of applying the batch again. The server retains operation status and item receipts for seven days. Changing the assignments creates a different operation.

6. Check the result in the same assignment scope that you changed. Successful assignments update the category and optional budget line item on the original transaction. See the result in Sloth Money → Transactions, or re-run the original transaction query without --uncategorized and inspect both the personal and joint category fields:

sloth-agent transactions --assignment-scope personal --limit 50

The transaction should also disappear from the matching --uncategorized query. Confirm that an existing assignment in the other scope was not changed. Assignments do not create a separate list.

Share and categorise a transaction

Find an owned, unshared booked transaction:

sloth-agent transactions --shared=false --q "sainsbury" --limit 20

Copy its exact transactionRef into assignments.json. This example shares the transaction 60/40, keeps £5 for you personally, and categorises the shared remainder as Groceries in Joint:

{
  "assignments": [
    {
      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
      "sharing": {
        "isShared": true,
        "shareRatio": 0.6,
        "userExclusiveAmountPence": 500,
        "partnerExclusiveAmountPence": 0
      },
      "assignmentScope": "joint",
      "categoryId": "groceries"
    }
  ]
}

Preview stays local and does not load credentials or call the API:

sloth-agent assign --input assignments.json

Apply with a token created using Allow changes, then read back the same state shown in the Web App:

sloth-agent assign --input assignments.json --apply
sloth-agent transactions --shared=true --q "sainsbury" --limit 20

When sharing contains only "isShared": true, a first share uses the couple's saved ratio, falling back to 0.5, and shares the full amount. On an already shared transaction, omitted split fields preserve their current values. Set both exclusive pence fields to zero to share the full amount again.

To unshare, send "sharing": { "isShared": false } without ratio or exclusive fields. Sloth clears the active split but keeps the Joint category dormant, so sharing it again restores that category. Current-period Joint pay income is reconciled; interest and completed periods keep their existing behaviour.

Sharing is available only for your booked personal-account transactions when you have an active partner and Joint budget. Partner-owned rows and native joint-account rows cannot be changed this way. Foreign-currency rows can still be shared for settlement, but their returned contribution has eligible: false and included: false.

If a combined item omits assignmentScope, the category uses Joint when you have no exclusive amount and Personal when you do. Category-only items retain their existing Personal/native default. Each item commits atomically, while a bulk request remains best-effort across items.

Review a temporary budget

These commands are available from the source checkout and are not yet in the published npm release.

Set up a temporary budget from the dropdown below Personal / Joint on the Budget page, using an existing Spend Goal or a new one. Its name and total come from that Goal. The Goal's funding accounts stay separate from the spending breakdown.

sloth-agent goal-budgets
sloth-agent transactions --goal-budget-ref PASTE_THE_EXACT_BUDGET_REF_HERE --assignment-scope personal

Use --assignment-scope joint for a joint budget. Copy budgetRef and category and line-item IDs from goal-budgets. The transaction filter covers the budget's whole lifetime unless you also pass dates, including manually entered payments. Refunds reduce spending. Summary and category amounts are in minor currency units (pence for GBP); the Goal's targetAmount is in major units.

Save this as holiday-assignment.json, replacing the placeholders with returned IDs:

{
  "assignments": [{
    "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
    "assignmentScope": "personal",
    "goalBudgetRef": "PASTE_THE_EXACT_BUDGET_REF_HERE",
    "categoryId": "PASTE_THE_EXACT_CATEGORY_ID_HERE",
    "lineItemId": "PASTE_THE_EXACT_LINE_ITEM_ID_HERE"
  }]
}

sloth-agent assign --input holiday-assignment.json
sloth-agent assign --input holiday-assignment.json --apply

Set goalBudgetRef to null and supply a monthly category to move the portion back to the monthly budget. Omitting the field preserves its current destination. Each personal or joint portion has one destination; category splits stay within that destination. Holiday spending stays in account totals and partner settlement, but leaves monthly category spending. No money is transferred or reserved. Restore a closed Goal before changing its budget or assignments. Create and edit the category breakdown in the app. The owner edits a joint plan; a current partner can read it and assign shared spending.

Other workflows

Read a personal or joint budget. Omit --period to use Sloth's current budget period:

sloth-agent budget --scope personal --period 2026-08

The result includes the budget period and status, currency, the effective plan, stored funding amounts when available, categories, line items, and planned amounts in pence.

Read booked activity for the current or a historical Sloth period:

sloth-agent budget status --scope personal
sloth-agent budget status --scope personal --period 2026-07

The period key names the calendar month containing that Sloth period's start boundary. Its end date can fall in the following month.

The current period uses Sloth's normal once-per-UTC-day transaction refresh; historical periods are cache-only and return refresh: null. Activity contains nonnegative moneyInPence and moneyOutPence plus their difference as netPence. Income, Transfer, explicit None, budget categories, and observed custom categories are normal rows. A transaction with no category at all is reported separately under activity.uncategorized.

A completed current-period refresh updates the Budget balance audit for any configured backing accounts. A same-day cached read does not add another audit checkpoint.

budget contains assigned, spent, and available category amounts when a trustworthy period plan exists. It is null when it does not; activity still returns. The response includes only the period budget currency and silently ignores rows in other currencies. This command is read-only.

Estimate the backing account balance through the current budget end date:

sloth-agent budget cashflow --scope personal
sloth-agent budget cashflow --scope joint

Scope is required. This cached, read-only command requires agent:read; it never refreshes banks or saves preferences. Choose one backing account per budget in Settings first. An unavailable result gives a reason instead of a zero balance. Available JSON includes account, period, startingBalancePence, remainingSpendingPence, closingBalancePence, firstNegativeDate, minimumBalancePence, items, and dailyBalances. Missing or old update times are flagged stale. If both budgets use the same account, their spending is combined once; an earlier end for the other budget is flagged as incomplete.

The calculation subtracts booked spending from planned amounts. For example, £400 planned, £100 assigned and £50 spent leaves £350 to forecast. Moving assigned budget money does not move bank cash or change this forecast. Dates use spending history from at least two of the last three periods; otherwise the amount falls tomorrow, or today when the period ends today. Future income and transfers are excluded. Pending payments are not reconciled and may be counted twice against the cached balance and remaining plan. There is no --period or --apply option.

Update selected line-item amounts by creating budget.json:

{
  "allocations": [
    {
      "categoryId": "groceries",
      "lineItemId": "weekly",
      "plannedPence": 45000
    }
  ]
}

Preview locally, then apply the same file:

sloth-agent budget update \
  --scope personal \
  --period 2026-08 \
  --input budget.json

sloth-agent budget update \
  --scope personal \
  --period 2026-08 \
  --input budget.json \
  --apply

The update starts from the complete selected-period budget, changes the listed line items, then overwrites the selected period and every explicit future plan with that complete result. A later update from another period overwrites that period and everything after it. Earlier and historical periods remain unchanged.

Without --apply, the CLI validates the file locally and does not load a token or contact Sloth Money. Applying requires a write-enabled token.

Move current assigned money between two categories, or use the reserved to-assign ID to move money to or from To Assign:

sloth-agent budget move \
  --scope personal \
  --from-category-id activities \
  --to-category-id groceries \
  --amount 52.95

sloth-agent budget move \
  --scope personal \
  --from-category-id activities \
  --to-category-id groceries \
  --amount 52.95 \
  --apply

Copy category IDs from sloth-agent budget output. --amount is expressed in the budget currency and accepts up to two decimal places; the CLI converts the decimal digits exactly and sends a positive safe-integer number of pence to the API. Without --apply, the command validates and prints the exact request without loading credentials or contacting Sloth Money.

Applying subtracts and adds the amount atomically, records the movement in the budget history, and returns the affected assigned balances. It does not change planned line-item amounts or future budget plans. Like the UI, it permits a source category or To Assign to become negative; an automated workflow should choose donors from its own available-balance policy. Historical periods cannot be changed, and applying requires a write-enabled token.

Create or rename a custom category. Writes are previews until --apply is present:

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:

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:

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:

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, connectionState, isGoalFundingAccount, and partnerVisibility. 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.

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:

sloth-agent transactions \
  --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE \
  --limit 50

Copy the value from sloth-agent accounts. Account references are the public account identifier for transaction filtering.

Account changes are previews unless --apply is present. Connected accounts support a private Sloth name, Goal-funding eligibility, and partner visibility. Manual current accounts support their institution, name, currency, and ownership. Manual balance accounts also support balance, Savings/Investments type, and Goal-funding eligibility. Partner-owned shared accounts return an explanatory error.

sloth-agent accounts update \
  --account-ref sloth_account_v1_... \
  --institution-name "Hargreaves Lansdown" \
  --account-name "Stocks & Shares ISA" \
  --currency GBP \
  --ownership individual \
  --balance-amount 12500.75 \
  --account-type investments \
  --goal-funding-account false \
  --partner-visibility holdings

sloth-agent accounts update \
  --account-ref sloth_account_v1_... \
  --partner-visibility balance \
  --apply

sloth-agent accounts update \
  --account-ref sloth_account_v1_... \
  --use-provider-name \
  --apply

--account-name sets the private name shown in Sloth for either a connected or manual account. For a connected account, --use-provider-name clears that private override and returns to the latest name supplied by the bank. The two name options are mutually exclusive.

Read the same current position from your, your partner's, or the combined household perspective:

sloth-agent portfolio
sloth-agent portfolio --view partner
sloth-agent portfolio --view household

The command waits up to 45 seconds for eligible linked balances to refresh, then returns cached data if work continues. Partner accounts appear only when their owner has shared the balance or linked holdings. Sharing is for household planning only. It does not change account ownership, transaction access, Goal funding, or who can move money. Totals use the viewer's budget currency and exclude other native currencies without converting them.

A completed balance refresh updates the Budget balance audit for any configured backing accounts. A same-day cached read does not add another audit checkpoint.

Archive an owned manual account. The account disappears from active Sloth surfaces, but its underlying records are retained. Repeating an applied removal is safe and returns changed: false.

sloth-agent accounts remove --account-ref sloth_account_v1_...
sloth-agent accounts remove --account-ref sloth_account_v1_... --apply

Read linked investment accounts and their cached holdings:

sloth-agent investments
sloth-agent investments --account-ref sloth_account_v1_...

Investment reads are cache-only and do not refresh a brokerage. Holding quantities, unit prices, market values, currencies, and freshness are returned in provider-native terms. They are not converted or guaranteed to reconcile to an account total reported in another currency. An investment account total and its nested holdings describe the same portfolio, so do not add them together. Do not add values in different currencies without an explicit conversion. Caller-owned personal and joint linked investment accounts are included; partner-owned accounts, manual holdings, and investment activities are not.

List your goals:

sloth-agent goals

Goal writes are previews unless --apply is present:

sloth-agent goals create \
  --name "Emergency fund" \
  --target-amount 12000 \
  --type keep \
  --account-ref sloth_account_v1_...

sloth-agent goals create \
  --name "Wedding" \
  --target-amount 22000 \
  --target-month 2027-06 \
  --type spend \
  --account-ref sloth_account_v1_... \
  --apply

Without --apply, Goal creation authenticates and asks Sloth to calculate the Goal without writing it. Preview and apply use the same active-scenario planner and return forecastMonthKey, the effective priority, the funding configuration, current allocations, forecast allocations, and forecastBasis. A null forecast includes the final projected month. The CLI does not compare the desired and forecast dates or return affordability advice.

Automatic funding is the default. Repeat --account-ref to select several personal eligible accounts in the Goal currency. Sloth allocates alphabetically by displayed institution/account label, then account reference for ties, regardless of flag order. Renaming an account can change allocation. Current savedAmount, progressPercent and allocations use cached balances; forecastAllocations describes projected funding. hasMissingAccounts identifies incomplete data rather than treating it as a zero balance.

sloth-agent goals create --name "Wedding" --target-amount 6000 --type spend \
  --account-ref PASTE_SAVINGS_REF_HERE --account-ref PASTE_ISA_REF_HERE

For fixed shares, save this JSON as funding.json, replacing each placeholder with an exact reference from sloth-agent accounts:

{
  "mode": "explicit",
  "allocations": [
    { "accountRef": "PASTE_SAVINGS_REF_HERE", "amount": 4000 },
    { "accountRef": "PASTE_ISA_REF_HERE", "amount": 2000 }
  ]
}

sloth-agent goals create --name "Wedding" --target-amount 6000 --type spend --funding-input funding.json
sloth-agent goals create --name "Wedding" --target-amount 6000 --type spend --funding-input funding.json --apply
sloth-agent goals update --goal-id GOAL_ID --target-amount 6000 --funding-input funding.json --apply

--funding-input and --account-ref are mutually exclusive. Positive shares must sum exactly to the target. To change an explicit Goal's target, include the matching split in the same update; invalid changes save neither value. Update previews check the supplied file locally; the server validates it against the complete saved Goal on apply. With £1,000 savings and £10,000 ISA, a £4,000/£2,000 split counts £3,000 today; a lower-priority Goal can use the remaining £8,000 ISA. Shortfalls never spill into another explicit share. Funding choices do not transfer money or use partner accounts.

Every goal is either Keep or Spend. A Keep goal continues reserving its funded money. A Spend goal reserves money until you explicitly mark it spent. Goal list, create, and update output includes lowercase goalType and nullable spentAt; spentAt is an ISO timestamp only after a Spend goal is marked spent.

Use the id from list or create output to update a goal, change its type, or move it in the priority order:

sloth-agent goals update \
  --goal-id goal-id \
  --target-month 2027-12 \
  --account-ref sloth_account_v1_... \
  --type spend \
  --apply

sloth-agent goals update \
  --goal-id house-goal-id \
  --priority 2 \
  --apply

Marking spent and restoring are also previews by default:

sloth-agent goals mark-spent --goal-id goal-id
sloth-agent goals mark-spent --goal-id goal-id --apply

sloth-agent goals restore --goal-id goal-id
sloth-agent goals restore --goal-id goal-id --apply

sloth-agent goals delete --goal-id goal-id --apply

Updates are partial. Use --clear-target-month to remove the optional month. A Keep goal cannot be marked spent. A spent goal must be restored before its type can change; the API returns these lifecycle conflicts without hiding the required recovery action. Restoring clears spentAt and returns the goal to allocation at its saved priority. Deleting a goal also removes its forecast assignments and drift history.

Goal sharing remains app-managed. Goal list output includes a one-based priority; 1 is highest. Moving one goal automatically shifts the goals between its old and new positions. Sloth recalculates the active-scenario roadmap before every applied Goal mutation and returns the updated forecast.

List the scenarios that supply assumptions to that roadmap:

sloth-agent scenarios

Create a monthly contribution choice. Preview is the default and performs zero writes; add --apply after reviewing the returned scenario and recalculated Goals:

sloth-agent scenarios create \
  --month 2026-09 \
  --name "Deposit £100 into the shopping pot each month?" \
  --account-ref sloth_account_v1_... \
  --recurring-amount 100

Creation adds No and Yes options and activates Yes. The recurring contribution continues until a later active scenario changes it. A one-off amount applies only in the scenario month. Scenarios alter the forecast; they do not move money.

Use stable IDs from scenarios output to edit or select an option:

sloth-agent scenarios update \
  --month 2026-09 \
  --option-id yes \
  --account-ref sloth_account_v1_... \
  --recurring-amount 125 \
  --apply

sloth-agent scenarios activate \
  --month 2026-09 \
  --option-id no \
  --apply

sloth-agent scenarios delete --month 2026-09 --apply

For recurring contributions, --recurring-amount 0 explicitly stops the earlier amount. --clear-recurring removes this month's override, so the earlier recurring amount continues. Contribution updates use the active option when --option-id is omitted.

Read uncategorised contributions to the joint budget:

sloth-agent transactions --assignment-scope joint --uncategorized

Include the current pending snapshot while reviewing transactions:

sloth-agent transactions --include-pending

This option reuses the transaction command's normal linked-bank refresh. It does not force a second refresh. Sloth Money keeps the latest complete pending observation until the next fully successful refresh, including an empty result. Booked rows remain in transactions; pending rows appear in pending.transactions with writable: false and writeBlockReason: "pending", so they cannot be passed to assign. A current empty list means the latest complete observation had no matching pending rows. unavailable means no valid complete snapshot is available and must not be interpreted as proof that there are no pending payments. Date, text, and account filters apply to pending rows; categorisation and pagination filters remain booked-only.

The first transaction read after the UTC day changes may refresh linked bank data. The CLI waits up to 45 seconds for that refresh to persist, then returns the requested booked transactions. If the refresh is still running, partially fails, or fails globally, readable cached transactions are still returned with a structured refresh object:

{
  "refresh": {
    "status": "in_progress",
    "reason": "wait_timeout",
    "utcDate": "2026-07-31"
  }
}

reason: "quota_exceeded" means the UTC-day provider refresh allowance is exhausted. The command still returns the latest cached booked transactions; it does not expose the provider's error message.

reason: "checkpoint_failed" means the provider refresh completed but the Budget balance-audit checkpoint failed. Cached booked transactions remain available, and a same-day read retries only the checkpoint.

A completed refresh also updates the Budget balance audit for any configured backing accounts. A same-day cached read reuses the existing data and does not add another audit checkpoint.

Re-run the transaction query later to observe the completed refresh. A partial account failure remains eligible for an automatic retry.

Read partner settlement context when an incoming payment may be a recorded partner payment:

sloth-agent partner status

The read-only response reports whether a mutual partner is connected, the current settlement direction and amount in pence, and recent sent or received payments. It uses opaque payment references and paginates with nextCursor. The command does not refresh bank accounts or change partner records.

Set "assignmentScope": "joint" on an assignment to categorise the eligible shared portion for the joint budget.

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.

Booked transactions and opt-in pending rows include counterpartyName and transactionReference when the bank supplies them. The Agent API does not return provider-native debtor, creditor, or raw remittance fields.

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:

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.

Configuration and output

The CLI defaults to https://budget.slothmoney.app. For local development, set SLOTH_AGENT_API_BASE_URL=http://localhost:4000 or pass --base-url http://localhost:4000. Non-local HTTP origins are rejected so a token cannot be sent over an unencrypted connection.

Stored credentials are separated by normalized API origin. One credential is stored per origin; log out and log in again to switch accounts on the same origin.

Command results are JSON on stdout. Diagnostics are written to stderr.

| Exit code | Meaning | | --- | --- | | 0 | Success | | 1 | API, network, credential-store, response-validation, or partial assignment failure | | 2 | Invalid command, option, URL, date, auth input, goal input, or assignment input | | 3 | No credential or native secure storage is unavailable |

Assignment writes run as durable, best-effort operations. The CLI waits for the terminal result and returns exit code 1 when any item failed, while preserving the complete succeeded and failed arrays on stdout. Re-running an interrupted command with the same input resumes the same server operation.

Development

npm ci
npm run verify
npm run release:preflight

npm run test:package packs the exact npm artifact, installs it into a clean temporary project, and runs the installed binary.

npm run release:preflight reports the local, packed, npm-registry, and every PATH-resolved globally installed version, then exercises every parser command's nested help. It fails when a parent help page stops advertising one of its child commands.

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. It requests full registry metadata because the abbreviated install index can lag behind an accepted publication. The temporary directory is removed after the check.

Fill pots and fund ahead

sloth-agent budget fill --scope personal --mode auto
sloth-agent budget fill --scope joint --mode manual --input overrides.json
sloth-agent budget fund-ahead --scope personal
# Replace the placeholder with previewFingerprint from the matching preview:
sloth-agent budget fill --scope personal --mode auto --apply --expected-preview <previewFingerprint>

These commands contact Sloth Money for a read-only preview. They need agent:read; applying needs agent:write, --apply, and --expected-preview. Keep all other arguments the same. Changed funding inputs return a conflict: preview again and review before applying. After an uncertain response, inspect the budget before retrying. Neither command changes planned targets.

Auto-fill tops up max(0, target − assigned), without funding spent money again. It reserves explicit overrides first, then uses remaining To Assign in the web category order. A partial auto-fill is allowed. Manual-fill adds the full target for each category unless overridden; a total exceeding To Assign cannot apply. Fund-ahead moves all positive To Assign to next-period reserve, which returns to To Assign when the next period is prepared. It accepts no amount or overrides.

An optional overrides file contains:

{"allocations":[{"categoryId":"groceries","amountPence":10000}]}

Supply up to 400 unique budgetable category IDs with additional nonnegative, safe-integer pence amounts. Zero skips a category. Omitted categories follow the mode defaults. Unknown fields, duplicate IDs, and invalid amounts are rejected. Use budget or categories to discover IDs.

--period YYYY-MM defaults to the current configured Sloth period. Historical and future periods are rejected. Previews can project new-period carryover without writing; apply saves preparation, funding, and category movement history atomically. No-op requests write nothing.

Results contain previewFingerprint, applied, canApply, noOp, preparationRequired, scope, period, currency, mode, category IDs/names, targets, assigned amounts before/after, proposed additions, shortfall, total assigned, and To Assign/reserve before/after. Fund-ahead returns no category allocations. The versioned funding schema is generated from sloth-budget with the existing contracts:sync command, alongside transaction schemas.