iou-cli 0.3.0

IOU CLI client

IOU CLI

As in I o(we) (yo)u 5€.

Shared expenses management tool that does not spy on you - the CLI interface.

Features

• transactions
  • git-like creation and editing of transactions
  • split types equal, unequal, share, percentage, adjustment
  • transaction description
  • setting the date on transactions
  • multi-deposits
  • listing and inspecting transactions
  • deletion
• groups
  • creation
  • adding users
  • adding system users
• payday transaction for settling up
• balance inspection
• instance/session switching

Upcoming

• transactions
  • search by text, date and amount
• groups
  • deletion
• import
  • splitwise CSV format
• system users
  • invites
• notifications
  • notification client creation, deletion, inspection
  • notification retrieval and read-receipt

Contributing

git clone ssh://git.notourserver.de:2222/iou/cli.git
cd cli
python -m venv --upgrade-deps .venv
source .venv/bin/activate{.fish} # omit depending on shell used
pip install -r requirements-uv.txt # install alternative package manager
uv pip install -e .[dev]
iouctl --help
pre-commit install # sets up static type checking, linting, etc.

Run linting and tests:

pytest --cov-report term --cov-report html --cov-report=xml:pytest-cobertura.xml --cov=iou test
pre-commit run --all

You may want to build a python package and upload it using twine:

python -m build
twine upload --verbose --skip-existing dist/*

Examples

Login using an OIDC IdP used by the IOU server.

$ iou login http://localhost:8000
Not logged in!
Please visit https://auth.221b.uk/realms/221b/device, login and enter the following code.
User code: HLWB-SPOW
Request expires in 600s
Device code authorized.
Loading user profile...
Login successful!

$ iou session
Logged in as 37e282fa-5761-443c-bbde-f8f13bbb8084 at 'http://localhost:8000'
Session expires on '2025-06-15 10:54:06.859556' (in 13 days)

Retrieve the list of groups to get a group UUID.

$ iou groups list
Groups
------
90269a57-7c92-446e-b00a-ed6425a37430: test1
   user2 ([e-mail])
   user1 ([e-mail])

Alternatively create a new group.

$ iou groups create somegroup

Then begin to craft a new transaction, in a git-like style.

$ iou begin 90269a57-7c92-446e-b00a-ed6425a37430
Transaction started. Type 'iou t(ransaction) deposit' to add a deposit.
$ iou add sherlock
$ iou add moriarty
$ iou status
Per group balance
    test-group (sherlock, moriarty): you are good
Total balance: you are good
---
Uncommitted transaction between sherlock, moriarty
Group: 90269a57-7c92-446e-b00a-ed6425a37430
Split type: None
Description:
Date: 2026-03-07 14:31:12

Users:
    sherlock (e675c6ff-1a94-4751-bc6b-d64a165c8750)
    moriarty (05025003-aa13-4d54-8904-fe7337ca25e2)

Deposits:
    No deposits yet.

Adjustments:
    No adjustments yet.

Split: you are good

$ iou split equal
$ iou deposit e675 20
$ iou describe "I owe you, sherlock"
$ iou status
Uncommitted transaction between sherlock, moriarty
Group: 90269a57-7c92-446e-b00a-ed6425a37430
Split type: equal
Description: I owe you, sherlock
Date: 2026-03-07 14:31:12

Users:
    sherlock (e675c6ff-1a94-4751-bc6b-d64a165c8750)
    moriarty (05025003-aa13-4d54-8904-fe7337ca25e2)

Deposits:
    No deposits yet.

Adjustments:
    No adjustments yet.

Split: you are owed 10€

$ iou commit  # transaction is now closed and pushed to the server
$ iou status
Per group balance
    test-group (sherlock, moriarty): you are owed 10€
Total balance: you are owed 10€
No transaction in progress.

Open an existing transaction for edit (find a transaction to edit via iou transactions list).

$ iou edit 9026 f825d150-51cb-4283-887e-86ad69f85965  # partial UUID is also allowed
Transaction opened for edit.