future-healthcare-cli

Python library and optional CLI for Future Healthcare.

The CLI helps with common refund flows:

• login stores your API token locally
• check lists refund status/history
• nifs looks up known refund addresses for a business NIF
• submit submits a new expense with receipt metadata

Install

Install the CLI with uv:

uv tool install 'future-healthcare[cli]'

This makes the future-healthcare command available on your system.

Run Without Installing

You can also run it directly with uvx:

uvx --from 'future-healthcare[cli]' future-healthcare --help

Usage

Log in first:

future-healthcare login -u YOUR_USERNAME -p YOUR_PASSWORD

Check existing refunds:

future-healthcare check

Look up the available addresses for a business NIF:

future-healthcare nifs 509876543

This prints one building per line as Building Name (address).

Submit a receipt by passing the required fields explicitly:

future-healthcare submit ~/Downloads/example-receipt.pdf \
  --business-nif 509876543 \
  --invoice-number 'INV 2026/0001' \
  --total-amount 40 \
  --date '2026-03-14'

The submit command may prompt you to choose the insured person, service, or building when multiple matches are available. Use --building to select a building/address up front for non-interactive runs. Pass only the building name from future-healthcare nifs, not the address in parentheses. Receipt data extraction happens before calling the CLI. Agent users can use the bundled Codex skill in .agents/skills/future-healthcare-cli/SKILL.md to inspect the receipt, extract the required fields, and then run future-healthcare submit with explicit flags.

Configuration

The CLI reads defaults from ClassyClick's default config.toml location. You can inspect the active configuration and its file path with:

future-healthcare config

To edit it in $VISUAL or $EDITOR:

future-healthcare config --edit

Configuration mirrors the CLI command options:

[submit]
service = "Dentist"

[login]
username = "YOUR_USERNAME"

You can also keep multiple environments in the same file and select one with --env:

default_env = "personal"

[submit]
service = "Dentist"

[env.personal.submit]
person = "Alice"

[env.work.submit]
person = "Bob"

Then run:

future-healthcare --env work submit ~/Downloads/example-receipt.pdf \
  --business-nif 509876543 \
  --invoice-number 'INV 2026/0001' \
  --total-amount 40 \
  --date '2026-03-14'

Use group-level path flags when you want local state somewhere else:

future-healthcare --token-path ~/.future-healthcare/token.txt --log-dir ~/.future-healthcare/logs login \
  -u YOUR_USERNAME \
  -p YOUR_PASSWORD

Local Data

By default, the CLI stores local state next to the selected configuration file, including:

• token.txt for the login token
• config.toml for CLI defaults
• logs/ for submission logs and copied input files

Development

See CONTRIBUTING.md.