cantaloupe-downloader/AGENTS.md

Cantaloupe Downloader — Agent Guide

CLI tool for exporting machine list data (Excel .xlsx) from mycantaloupe.com. Used as the upstream data source for the Canteen asset tracking pipeline.

Stack

• Python 3.11+, click (CLI framework)
• httpx (async HTTP client with anti-forgery token handling)
• playwright (browser automation fallback for JS challenges)
• openpyxl (Excel file reading)
• respx / pytest (testing)

Project Structure

cantaloupe/
  __init__.py
  __main__.py       # Entry: python -m cantaloupe
  cli.py             # Click CLI: export, diff, configure commands
  config.py          # Config file management (~/.cantaloupe.env)
  diff.py            # Compare two Excel exports

src/
  auth.py            # Login: httpx anti-forgery token or Playwright fallback
  download.py        # Export POST → save .xlsx

tests/
  test_auth.py
  test_cli.py
  test_diff.py
  test_download.py

API.md               # API investigation notes
README.md
requirements.txt

How to Run

# Export machines list
python -m cantaloupe export

# With scheduled-output path
python -m cantaloupe export --scheduled

# Compare two exports
python -m cantaloupe diff file1.xlsx file2.xlsx

# Configure credentials
python -m cantaloupe configure

Key Architecture

• Two auth strategies:
  1. Primary: httpx — anti-forgery token extraction from HTML, form-based login
  2. Fallback: Playwright — full browser automation for JS challenges
• Config stored in ~/.cantaloupe.env (credentials)
• Exports go to ~/cantaloupe-exports/ with manifest tracking via manifest.json
• diff command compares two exports cell-by-cell

Production

• CLI tool only — no server, no systemd
• Triggered via cron: cantaloupe-sync.sh runs every 6 hours
• Part of the Canteen pipeline: Cantaloupe → downloader → sync API

Environment Variables

Var	Description
CANTALOUPE_EMAIL	Login email
CANTALOUPE_PASSWORD	Login password
CANTALOUPE_OTP_SECRET	Optional TOTP secret for 2FA

Pitfalls

• Cantaloupe may show JS challenges — Playwright fallback handles this but requires browser binaries (playwright install chromium)
• Export format may change on Cantaloupe's side (they're a third-party SaaS) — diff.py detects structural changes
• Auth tokens expire; each run re-authenticates