Developer Documentation

CLI Reference & API Docs

Everything you need to integrate with Taxxie, automate your workflow, or just get started fast.

Quick Start

Get from zero to your first receipt in under two minutes. You will need Python 3.12+ and an authenticator app (Google Authenticator, 1Password, or Authy).

  1. Install Taxxie

    Terminal
    $ pip install taxxie

  2. Create your account

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

    A QR code will appear in your terminal. Scan it with your authenticator app to set up TOTP.

  3. Log in

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

  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)

CLI Reference

All commands follow the pattern taxxie <command> [subcommand] [flags]. Use --help on any command for full usage details.

Command Description
register Create a new Taxxie account with TOTP authentication
login Authenticate and store a JWT session token locally
receipt upload Upload a receipt image for OCR extraction
receipt list List and filter your uploaded receipts
return generate Generate an ATO-compatible tax return

taxxie register

Create a new account. Displays a QR code for setting up TOTP in your authenticator app. The QR code is shown only once.

Flag Required Description
--email Yes Your email address (used as your account identifier)
--name No Your display name
Terminal
$ taxxie register --email craig@example.com --name "Craig B" ✓ Scan the QR code with your authenticator app. [QR code displayed in terminal] ✓ Account created. Welcome to Taxxie!

taxxie login

Authenticate with your email and TOTP code. On success, a JWT token is saved to ~/.config/taxxie/token.json and used for subsequent requests.

Flag Required Description
--email Yes Your registered email address
--totp No TOTP code (prompted interactively if omitted)
Terminal
$ taxxie login --email craig@example.com --totp 314159 ✓ Logged in. Token saved to ~/.config/taxxie/token.json

taxxie receipt upload

Upload a receipt image for OCR processing. Taxxie extracts the merchant, date, total, GST component, and suggests an ATO deduction category.

Flag Required Description
<file> Yes Path to receipt image (JPEG, PNG, or PDF)
--category No Override the auto-detected ATO category code (e.g. D5)
--description No Manual description to attach to the receipt
--year No Financial year override (e.g. 2025-26). Auto-detected from receipt date by default
Terminal
$ taxxie receipt upload bunnings-drill.jpg --category D5 Uploading... done. ✓ Extracted: Bunnings Warehouse — $189.00 (GST $17.18) ✓ Category: Work-related expenses (D5) Receipt ID: rx_a1b2c3d4

taxxie receipt list

List your uploaded receipts with optional filtering by financial year, category, or status.

Flag Required Description
--year No Filter by financial year (e.g. 2025-26)
--category No Filter by ATO category code
--status No Filter by status: confirmed, review, or all
--format No Output format: table (default), json, or csv
Terminal
$ taxxie receipt list --year 2025-26 --format table ID DATE MERCHANT AMOUNT CAT STATUS -------- ---------- ----------------- -------- ----- --------- rx_a1b2c3 2025-08-12 Officeworks $54.99 D5 confirmed rx_d4e5f6 2025-09-03 Bunnings $189.00 D5 confirmed rx_g7h8i9 2025-11-14 Uber (airport) $42.50 D1 review -------- ---------- ----------------- -------- ----- --------- 3 receipts | Total: $286.49 | GST: $26.04

taxxie return generate

Generate an ATO-compatible tax return from your confirmed receipts. The output can be saved as a file for lodgement or review by a tax agent.

Flag Required Description
--year Yes Financial year to generate for (e.g. 2025-26)
--output No Output file path (defaults to taxxie-return-2025-26.json)
--format No Output format: json (default) or csv
--include-review No Include receipts with review status (excluded by default)
Terminal
$ taxxie return generate --year 2025-26 Aggregating 47 confirmed receipts... ✓ Tax return generated. Total deductions: $4,812.50 GST credits: $437.50 Saved to: taxxie-return-2025-26.json

API Reference

The Taxxie REST API uses JSON over HTTPS. All endpoints require a valid JWT token in the Authorization: Bearer <token> header, except for registration and login.

Base URL: https://api.trytaxxie.com/v1

Register a new account

POST /auth/register

Create a new account. Returns a TOTP provisioning URI for authenticator app setup.

Request
curl
$ curl -X POST https://api.trytaxxie.com/v1/auth/register \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "name": "Your Name"}'
Response (201 Created)
JSON
{ "user_id": "usr_k9m2x7", "email": "you@example.com", "totp_uri": "otpauth://totp/Taxxie:you@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Taxxie", "message": "Scan the TOTP URI with your authenticator app. This secret is shown only once." }

Verify TOTP setup

POST /auth/verify

Confirm that the authenticator app is configured correctly by submitting a valid TOTP code. Required before first login.

Request
curl
$ curl -X POST https://api.trytaxxie.com/v1/auth/verify \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "totp_code": "482910"}'
Response (200 OK)
JSON
{ "verified": true, "message": "TOTP verified. You can now log in." }

Log in

POST /auth/login

Authenticate with email and TOTP code. Returns a JWT access token and a refresh token.

Request
curl
$ curl -X POST https://api.trytaxxie.com/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "totp_code": "314159"}'
Response (200 OK)
JSON
{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer", "expires_in": 3600 }

Refresh access token

POST /auth/refresh

Exchange a valid refresh token for a new access token without requiring TOTP re-authentication.

Request
curl
$ curl -X POST https://api.trytaxxie.com/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'
Response (200 OK)
JSON
{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer", "expires_in": 3600 }