wallos-fetcher/README.md

📦 Wallos Fetcher

Wallos Fetcher is a command-line utility designed to retrieve and export subscription data from a self-hosted Wallos instance—an open-source personal subscription tracker.

This script helps you keep track of all your recurring expenses and share that information in human-readable or machine-readable formats, making it especially useful for budgeting, personal finance planning, and digital legacy preparation for family members.

---

✨ Features

• 📄 Markdown output by default – easy to read, easy to share
• 💾 Export as Markdown, CSV, or JSON
• 🔍 Optionally include full subscription details (e.g., cycle, auto-renew, currency)
• 🗃 Output to a custom file
• 🧰 Lightweight, portable, and dependency-minimal (requires curl and jq)

---

🚀 Installation

git clone https://git.nickhepler.cloud/nick/wallos-fetcher.git
cd wallos-fetcher
chmod +x wallos-fetch.sh

🔧 Ensure you have curl and jq installed.

• Ubuntu/Debian:

  sudo apt install curl jq
  

• macOS (Homebrew):

  brew install curl jq
  

---

🧪 Usage

./wallos-fetch.sh [options]

✅ Example Commands

Purpose	Command
Default output as Markdown	./wallos-fetch.sh
Export as JSON	./wallos-fetch.sh --json
Export as CSV	./wallos-fetch.sh --csv
Include extended subscription data	./wallos-fetch.sh --full
Custom output filename	./wallos-fetch.sh --output mysubs.md
Combine options	./wallos-fetch.sh --csv --full --output mysubs.csv
Show help	./wallos-fetch.sh --help
Check script version	./wallos-fetch.sh --version

---

📄 Output Formats

🧾 Markdown (Default)

Designed for human readability and sharing with family members.

Includes:

• A title (# 🧾 Active Subscriptions Overview)
• A short description for context and legacy planning
• A table of subscriptions with essential or full detail (if --full used)

# 🧾 Active Subscriptions Overview

This document lists all recurring subscriptions tied to this household or individual. It includes costs, renewal dates, categories, and payment methods. This record is provided as a reference for financial planning, digital legacy management, or to assist family members in case of emergencies or estate matters.

_Last updated: 2025-04-21_

| ID | Name | Price | Next Payment | Category | Payment Method |
|----|------|-------|---------------|----------|----------------|
| 1  | Netflix | 17.99 | 2025-04-21 | Entertainment | Credit Card |

📊 CSV

Structured export for use in spreadsheets or data processing tools.

• Default fields: id,name,price,next_payment,category_name,payment_method_name
• --full option adds: currency_id,cycle,auto_renew, etc.

📦 JSON

Raw response data from the Wallos API—useful for backups or integrations.

---

🔐 Authentication

You can set your API key in one of two ways:

1. Environment Variable (Recommended)

This is the preferred and more secure method, especially for automation and scripting:

export WALLOS_API_KEY="your_api_key_here"

The script will automatically detect this variable and use it if API_KEY is not set inside the script.

2. Hardcoded in Script (Optional)

Open the wallos-fetch.sh file and manually set your API key by replacing this line:

API_KEY="${API_KEY:-$WALLOS_API_KEY}"

with:

API_KEY="your_api_key_here"

⚠️ Be cautious: hardcoding secrets in scripts can pose a security risk if the file is shared or version-controlled.

📜 License

This project is licensed under the GNU General Public License v3.0 or later.

---

🤝 Contributions

Feedback, bug reports, and pull requests are welcome!
Submit issues or improvements via your Gitea repository.

---

❤️ About Wallos

Wallos is an open-source personal subscription manager. Learn more or contribute to the main project here:

🔗 https://github.com/WallosApp/Wallos