Installation

Up and running in 30 seconds

One command to install. One command to register. Works on macOS, Linux, and Windows.

macOS

Python 3.12+ via Homebrew or python.org. Works on Apple Silicon and Intel.

Linux

Ubuntu, Debian, Fedora, Arch — anywhere Python 3.12+ runs. Native and WSL supported.

Windows

PowerShell or WSL. Python from python.org or the Microsoft Store.

Install with pip

The fastest way to get started. Requires Python 3.12 or later.

Terminal
$ pip install taxxie Collecting taxxie Downloading taxxie-0.1.0-py3-none-any.whl (42 kB) Installing collected packages: taxxie Successfully installed taxxie-0.1.0

Verify the installation:

Terminal
$ taxxie --version taxxie 0.1.0

Platform-specific notes

macOS

If you use Homebrew, make sure you have Python 3.12+:

Terminal — macOS
$ brew install python@3.12 $ pip3 install taxxie

Linux

On Ubuntu/Debian, you may need to install pip separately:

Terminal — Linux
$ sudo apt update && sudo apt install python3-pip $ pip3 install taxxie

Windows

Install Python from python.org or the Microsoft Store. Then open PowerShell:

PowerShell — Windows
PS> pip install taxxie

Alternatively, use WSL (Windows Subsystem for Linux) and follow the Linux instructions above.

Run with Docker

If you prefer not to install Python locally, run Taxxie as a Docker container. Your config is persisted in a named volume.

Terminal
$ docker pull ghcr.io/barkingiguana/taxxie:latest # Create an alias for convenience $ alias taxxie='docker run --rm -v taxxie-data:/root/.config/taxxie ghcr.io/barkingiguana/taxxie' # Now use it like the native CLI $ taxxie --version taxxie 0.1.0

To upload receipt files, mount the directory containing your images:

Terminal
$ docker run --rm \ -v taxxie-data:/root/.config/taxxie \ -v "$(pwd)":/receipts \ ghcr.io/barkingiguana/taxxie receipt upload /receipts/my-receipt.jpg
Account Setup

Register and authenticate

Taxxie uses TOTP (time-based one-time passwords) instead of API keys. It is the same standard your bank uses.

  1. Register your account

    Terminal
    $ taxxie register --email you@example.com ✓ Scan the QR code with your authenticator app. [QR code displayed in terminal] ✓ Account created. Welcome to Taxxie!

    A QR code appears in your terminal. This is your TOTP secret — it is shown only once. Scan it immediately with your authenticator app.

  2. Set up your authenticator app

    Open your authenticator app, tap "Add account" or the + button, and scan the QR code. Taxxie works with any TOTP-compatible app:

    • Google Authenticator Free, available on iOS and Android. Tap the + icon, choose "Scan a QR code", and point your camera at the terminal.
    • 1Password Built-in TOTP support. Edit any login item, add a "One-Time Password" field, and scan the QR code. Codes auto-fill on the desktop app.
    • Authy Free with encrypted cloud backup. Tap "Add Account", scan the QR code, and name it "Taxxie". Your codes sync across devices.
    • Any TOTP app Taxxie uses the standard TOTP protocol (RFC 6238). Any compliant app will work, including Bitwarden, Microsoft Authenticator, and KeePassXC.

  3. Log in

    Open your authenticator app, find the Taxxie entry, and enter the current 6-digit code:

    Terminal
    $ taxxie login --email you@example.com Enter your TOTP code: 482910 ✓ Logged in. Token saved to ~/.config/taxxie/token.json

    Your session token is stored locally. You will not need to re-enter your TOTP code until the token expires (1 hour, auto-refreshed).

  4. Upload your first receipt

    Terminal
    $ taxxie receipt upload officeworks-receipt.jpg Uploading... done. ✓ Extracted: Officeworks — $54.99 (GST $5.00) ✓ Category: Work-related expenses (D5)

    That is it. Your receipt is uploaded, OCR-processed, categorised, and ready for tax time.

Requirements

What you need

Taxxie is lightweight. Here is the full list of prerequisites.

Python 3.12+

Any OS with Python 3.12 or later. Check with python3 --version.

TOTP Authenticator

Any app that generates 6-digit time-based codes. Google Authenticator, 1Password, Authy, or similar.

Internet Connection

Required for uploads, login, and tax return generation. Receipt photos are processed server-side.

Next Steps

Ready to go?

Explore the full CLI and API documentation, or jump straight to uploading receipts.

Read the Docs Quick Start Guide