Command-line client

The patrimoine command talks to your server’s API from a terminal, so you can list and add accounts, balance snapshots, transactions and other records, and export your data, from a script, a cron job or a shell. It signs in with an API token.

Install

You need Python 3.13 and uv. From a checkout of the repository:

uv tool install ./cli
patrimoine --help

Create an API token

In Profile > API Tokens, create a token with a dedicated name such as cli. Its value starts with ptr_ and is shown once, so copy it right away.

A token gives full access to your account, the same as signing in. Revoke it from the same list at any time, which stops the command from working without affecting anything else. You can hold up to 10 tokens.

patrimoine login --url https://patrimoine.example.com

Without --url, the command uses PATRIMOINE_URL or asks for the address.

The command asks for the token without showing what you type, checks it against the server, and only then saves it. A refused token changes nothing. Values that do not start with ptr_ are refused before anything is sent.

Configuration

The server address and the token come from, in this order:

the --url and --token options;
the PATRIMOINE_URL and PATRIMOINE_TOKEN environment variables;
the file saved by patrimoine login, at ~/.config/patrimoine/config.json (or under $XDG_CONFIG_HOME when it is set).

The file is readable by you only, and the command warns if its permissions are looser. The --token option is visible to other users in the process list and stays in your shell history: prefer patrimoine login or the environment variable.

The command warns when the address starts with http:// and the server is not on your own machine, because the token would travel unencrypted. Use https://. A server that answers with a redirect is treated as an error and never followed, so the token is not sent anywhere else: use the address it points to.

Accounts

List your accounts:

patrimoine accounts list --search broker --limit 20

--search keeps the accounts whose name contains the text, --limit accepts 1 to 250 and --offset skips rows. Create an account:

patrimoine accounts add --name Savings --type savings --currency EUR

--type is one of checking, savings, investment, retirement, cash, real_estate, vehicle, collectible or other (the default). --currency is a three-letter code and defaults to EUR. --institution names the bank as free text, and --liability marks a loan or a debt.

Link a loan to the asset it finances while creating it:

patrimoine accounts add --name Mortgage --liability --link-to Home

--link-to takes the id or the exact name of one of your asset accounts and is meant for a loan (an account added with --liability): the server refuses a link on any other account, on a debt or on a trashed account.

Leave an account out of net worth, or count it again, with its id or its exact name:

patrimoine accounts edit Savings --exclude-from-net-worth
patrimoine accounts edit 7 --include-in-net-worth

The account stays visible but leaves every net-worth total (see Exclude from net worth for what that covers). accounts list shows an EXCLUDED column that reads yes for these accounts.

Link an existing account to an asset, or clear the link:

patrimoine accounts edit Mortgage --link-to Home
patrimoine accounts edit Mortgage --unlink

accounts edit takes exactly one of --exclude-from-net-worth, --include-in-net-worth, --link-to and --unlink: change one thing per call. accounts list ends with a LINKED column that shows the id of the linked asset (empty for an account with none). A loan has one asset and an asset can have several loans. The equity of an asset (its value minus its loans) is shown on the web only: see Accounts & Institutions.

Snapshots

List snapshots with their account names:

patrimoine snapshots list --limit 20

--limit accepts 1 to 500 and --offset skips rows. Record a balance with the account’s id or its name (case does not matter):

patrimoine snapshots add --account Broker --balance 1234.50 --date 2026-10-01

The date defaults to today. The balance is recorded in the account’s own currency. If a snapshot already exists for that account and day, it is updated, and the command says whether the snapshot was created, updated or unchanged.

Transactions

patrimoine transactions list --from 2026-01-01 --to 2026-01-31 --account Broker --type expense --search rent --limit 20

All the filters are optional. --type is income or expense, --limit accepts 1 to 250, and --account takes an id or a name. Add a transaction with a positive amount; --type says whether it is income or an expense:

patrimoine transactions add --account Broker --amount 42.10 --type expense --description "Rent"

The date defaults to today.

Budgets

patrimoine budgets list
patrimoine budgets set-limit 3 --month 2026-03 --amount 650
patrimoine budgets reset-limit 3 --month 2026-03
patrimoine budgets fill --month 2026-11 --mode average --months 6 --overwrite

The list shows each budget’s id, category (and subcategory), default limit and rollover. set-limit gives one month its own limit (--amount can be 0; a month before the budget was created is refused) and reset-limit returns that month to the default limit. fill sets a month’s limits in one go: --mode copy-previous copies the previous month’s own limit, and --mode average sets the average spending of the months with transactions among the last --months months before the target (1 to 24, default 3; the current month never counts). Months that already have their own limit are skipped unless you add --overwrite, fill works on all your active budgets unless you repeat --budget with an id, and it fails when there is no spending to average. --limit accepts 1 to 250 and --offset skips rows.

Pay schedules

patrimoine schedules list
patrimoine schedules add --name "Main job" --frequency semi_monthly --start 2026-11-01 --second-day 15 --default
patrimoine schedules edit 3 --name "Day job" --weekend before
patrimoine schedules edit 3 --clear-default
patrimoine schedules rm 3

The list shows each schedule’s id, name, cadence, first payday (START), next payday (NEXT, worked out by the server, - when no payday is left), the number of envelopes and savings goals that use it (USED), and a * on your default schedule. add needs --name, --frequency (weekly, semi_monthly, monthly, quarterly or yearly) and --start, the first payday as YYYY-MM-DD. --every repeats the cadence every N periods (1 to 52), --second-day (1 to 31) sets the second payday of a semi_monthly schedule, --weekend is none (the default), before or after and moves a payday that falls on a weekend, and --default makes it your default schedule. edit takes the schedule’s id and changes only the options you give; --default and --clear-default set or clear the default flag, and you cannot give both. rm deletes a schedule; the server refuses to delete your default schedule, or one that envelopes or savings goals still use (the error says how many). --limit accepts 1 to 250 and --offset skips rows.

Contribution templates

patrimoine templates list
patrimoine templates add --name "Monthly top-up" --kind per_month --amount 200
patrimoine templates edit 3 --amount 150
patrimoine templates rm 3

The list shows each template’s id, name, kind, amount and the number of savings goals that use it (USED). add needs --name, --kind (per_paycheck sets the amount aside on every payday, per_month once a month) and --amount (positive, in your base currency). --limit accepts 1 to 250 and --offset skips rows. edit takes the template’s id and changes only the options you give. rm deletes a template; the server refuses when savings goals still use it (the error says how many).

Envelopes and savings goals

patrimoine envelopes list
patrimoine envelopes add --name "Car tax" --target 120 --due 2027-03-01 --schedule "Main job"
patrimoine envelopes edit 7 --no-schedule
patrimoine goals list
patrimoine goals add --name Holiday --target 5000 --deadline 2027-07-01 --schedule 3
patrimoine goals add --name Holiday --target 5000 --deadline 2027-07-01 --template "Monthly top-up"
patrimoine goals edit 7 --no-template
patrimoine goals edit 2 --target 6000

The lists show each item’s id, name, target, due date or deadline, pay schedule and the amount to set aside per payday (- when there is none). SCHEDULE is the schedule the item uses, which is your default schedule when none was picked. envelopes add needs --name, --target (positive) and --due; --interval-months (1 to 120) repeats the envelope. goals add needs --name and --target, and --deadline is optional. --schedule takes a pay schedule’s id or exact name (see Pay schedules); an unknown schedule is refused before anything is sent. edit takes the item’s id and changes only the options you give; --no-schedule makes the item use your default schedule again, and you cannot give it together with --schedule. Archiving and deleting are not available from the command line. --limit accepts 1 to 250 and --offset skips rows. goals add and goals edit also take --template, a contribution template’s id or exact name (see Contribution templates); an unknown or ambiguous template is refused before anything is sent. goals list adds the template a goal uses and its projected completion, worked out by the server: the date, or reached, no schedule or too far, and - when the goal has no template. goals edit also takes --no-template to stop using a template; you cannot give it together with --template.

Planned transactions

patrimoine planned list --status overdue
patrimoine planned add --name Rent --amount 800 --type expense --frequency monthly --next-due 2026-11-01 --account Checking --payee Landlord

--status is one of upcoming, due, posted, overdue or failed; --limit accepts 1 to 250 and --offset skips rows. When you add an item, the amount is positive and --type is income or expense. --frequency is one_time, weekly, monthly, quarterly or yearly, and --next-due is the first due date. --month (1 to 12) is required for yearly items. --account (an id or a name) and --category (an id) are optional. --payee names an existing payee by its name or one of its other names, ignoring case and spacing; create a new payee first with patrimoine payees add, because an unknown payee is refused. The list shows each item’s payee.

Payees

patrimoine payees list --search amazon
patrimoine payees add --name Amazon

--search keeps the payees whose name contains the text, and the USES column counts the transactions that use the payee. --limit accepts 1 to 250 and --offset skips rows.

Notifications

patrimoine notifications list
patrimoine notifications read 42

The TYPE column shows the kind of notification as the server names it (budget_overspent, bill_due, stale_snapshot, net_worth_threshold or snapshot_reminder), and READ is empty while a notification is unread. --limit accepts 1 to 250 and --offset skips rows. Notifications are created by the server, so the command can list them and mark one as read, but not create, edit or delete one.

Holdings

patrimoine holdings list
patrimoine holdings add --ticker AAPL --account Broker --quantity 10 --cost-basis 150 --fee 4.50 --date 2026-01-15 --asset-class etf

The list shows each purchase’s ID, ticker, account, purchase date, quantity, cost basis, fee and total cost, then ASSET CLASS (empty when the purchase has none). TOTAL COST is the server’s figure: cost basis times quantity, plus the fee. add needs --ticker, --account (an id or an exact name), --quantity and --cost-basis, both positive. --fee is optional, zero or more, in the holding’s currency, and a negative fee is refused before anything is sent. --date is the purchase date (default today). --currency and --name are optional. --asset-class is optional and takes one of stock, etf, bond, crypto, cash, real_estate, commodity or other; any other value is refused before anything is sent, and a purchase added without it is unclassified. To change the class of an existing purchase, use the web app. --limit accepts 1 to 250 and --offset skips rows. Editing and deleting holdings are not available from the command line.

Export

patrimoine export snapshots --format csv > snapshots.csv
patrimoine export transactions --format xlsx -o transactions.xlsx
patrimoine export holdings -o holdings.csv
patrimoine export backup -o backup.json

snapshots, transactions and holdings export as csv (the default), xlsx or ods; snapshots and transactions also accept --from and --to to limit the dates. backup is always JSON.

The data goes to standard output, or to the file given with -o, which only you can read. The xlsx and ods formats are binary, so the command refuses to print them in a terminal: use -o or redirect the output. A backup holds your whole account, so keep the file somewhere safe.

Output and exit codes

Lists are plain-text tables with ISO dates and no colour. Add --json to get the server’s JSON instead, which is the only thing printed on standard output. Notes such as Showing 250 of 300. Use --offset to see more. and No snapshots found. go to standard error, so pipes stay clean.

Options such as --json work before or after the command name.

Exit code	Meaning
0	Success
1	The server or the network refused the request; the reason is printed as `error: ...`
2	Wrong usage, missing configuration, or a cancelled prompt

Sign out

Delete ~/.config/patrimoine/config.json, then revoke the token in Profile > API Tokens.