docs: Add CLI tool section and credential storage docs

2026-05-21 18:39:40 -04:00
parent 414a990cef
commit 58e221a0f5
+37 -4
@@ -14,6 +14,9 @@ CLI tool to authenticate with mycantaloupe.com and download the Machine List Exc
- **`src/auth.py`** — ASP.NET FormsAuth login (CSRF token + session cookies via httpx)
- **`src/download.py`** — Export download automation
- Authenticate → verify access → POST `/cs4/VueMachineList/ExcelExport` → save .xlsx
- **`cantaloupe/`** — Click CLI wrapper (`python -m cantaloupe export`)
- `cantaloupe/cli.py` — export + configure commands
- `cantaloupe/config.py` — credential management (`~/.cantaloupe.env`)
## Quick Start
@@ -21,15 +24,43 @@ CLI tool to authenticate with mycantaloupe.com and download the Machine List Exc
cd ~/projects/cantaloupe-downloader
pip install -r requirements.txt
# Set credentials
# Option 1: Save credentials to ~/.cantaloupe.env
python -m cantaloupe configure
# Option 2: Set environment variables
export CANTALOUPE_EMAIL="your@email.com"
export CANTALOUPE_PASSWORD="your-password"
# Download export
python -m src.download
# Output: ~/cantaloupe-exports/Machine List_YYYYMMDD_HHMMSS.xlsx
python -m cantaloupe export --output ./exports/
# Cron/scheduled mode
python -m cantaloupe export --scheduled --output /data/exports/
```
## CLI Commands
| Command | Description |
|---|---|
| `python -m cantaloupe export` | Download machine list Excel |
| `python -m cantaloupe configure` | Save credentials to `~/.cantaloupe.env` |
### Export Options
| Flag | Description |
|---|---|
| `-o, --output PATH` | Output directory or file path |
| `--headless / --visible` | Browser mode for Playwright fallback |
| `--scheduled` | Non-interactive cron mode |
| `--email TEXT` | Override account email |
| `--password TEXT` | Override account password |
## Credential Priority
1. `CANTALOUPE_EMAIL` / `CANTALOUPE_PASSWORD` environment variables
2. `~/.cantaloupe.env` file (created by `configure` command)
3. Interactive prompt (unless `--scheduled`)
## API Details
See [API Investigation](https://gitea.ourpad.casa/shawn/cantaloupe-downloader/wiki/API) for full endpoint documentation.
@@ -40,7 +71,7 @@ See [API Investigation](https://gitea.ourpad.casa/shawn/cantaloupe-downloader/wi
## Test Status
47 tests passing (27 auth + 20 download) as of commit `b5ae89a`.
86 tests passing (27 auth + 20 download + 39 CLI) as of commit `9c3d3ef`.
## Environment Variables
@@ -48,3 +79,5 @@ See [API Investigation](https://gitea.ourpad.casa/shawn/cantaloupe-downloader/wi
|---|---|---|
| `CANTALOUPE_EMAIL` | Yes | mycantaloupe.com login email |
| `CANTALOUPE_PASSWORD` | Yes | mycantaloupe.com login password |
Credentials can also be stored in `~/.cantaloupe.env` via `python -m cantaloupe configure`.