Connect your budget

You need three things, and fob-actual finds the last two for you:

	Example	Where it comes from
Sync server URL	`https://budget.example.com`	The address you open Actual at in your browser
Session token	a long random string	Created when you sign in with `auth login`
Sync ID	`1b4e28ba-…`	Picked automatically if the server has one budget. Otherwise from `budgets list`, or in Actual under Settings → Show advanced settings

Video coming soon

Connect fob-actual to your Actual server (2 min)

If you sign in to Actual with a password, one command does everything:

read -rs ACTUAL_PW        # type your Actual password, press Enter; nothing is shown
fob-actual auth login --profile household \
  --server-url https://budget.example.com --password "$ACTUAL_PW"
unset ACTUAL_PW

Signed in with password.
Stored session token for profile 'household'.
Token valid — 1 budget(s) visible.
Profile 'household' is bound to budget 'Household Budget'.

household is a name you choose for this profile. One profile points at one budget.

If your server uses OpenID (sign in with Google, Authentik and similar), there's no password to give. Run auth login without --password:

fob-actual auth login --profile household --server-url https://budget.example.com

It prints these steps, then asks you to paste the token:

Open your Actual server in a browser and sign in.
Open the browser's developer tools: Application → IndexedDB → actual → asyncStorage.
Copy the value of the user-token key.

Screenshot coming soon

Browser developer tools: IndexedDB, actual, asyncStorage, with the user-token key selected (value blurred)

auth login also prints a one-line snippet you can paste into the browser console to show the token instead.

Choose a budget#

If the server has more than one budget, auth login lists a command for each:

Multiple budgets found. Bind one with:
  fob-actual config profiles add household --sync-id bb8f9a60-9d9e-480f-8e61-b3a4615d843f   # Household Budget
  fob-actual config profiles add household --sync-id 903274c8-7095-4590-a0bc-fa7e11590e46   # Business Budget

Run the one you want. The profile keeps its server and token, and gains the budget. For a second budget, add another profile with its own name and --sync-id, then switch with --profile (see Profiles).

Encrypted budgets#

If you turned on end-to-end encryption in Actual, add the encryption password to the profile:

fob-actual config profiles add household --encryption-password "<encryption password>"

Check it works#

fob-actual auth status
fob-actual accounts list

Profile:            household
Server:             https://budget.example.com
Token:              valid
Budgets visible:    1
Bound budget:       Household Budget (1b4e28ba-2fa1-41d2-883f-0016d3cca427)

About session tokens#

Whether a token expires is a server setting (ACTUAL_TOKEN_EXPIRATION), which defaults to never. If yours expire, run auth login again when commands say the token is invalid.
A token can reach every budget its user can see on the server.
fob-actual auth logout forgets the token locally only. It stays valid on the server until it expires or the server clears its sessions.

Where credentials are stored#

Profiles live in ~/.fob/fob-actual/config.yml, written with mode 0600 so only your user can read it. The token and any encryption password inside are plain text. To use a different folder, set FOB_ACTUAL_CONFIG_DIR.

For workers, CI and containers, use environment variables instead. See Profiles.