175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
# 📦 Wallos Fetcher
|
||
|
||
Wallos Fetcher is a command-line utility designed to retrieve and export subscription data from a self-hosted [Wallos](https://github.com/WallosApp/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. It's especially useful for budgeting, personal finance planning, and digital legacy preparation for family members.
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- 📄 **Markdown output by default** – clean, readable reports
|
||
- 📊 **CSV output** – spreadsheet-friendly for Excel, Numbers, etc.
|
||
- 💾 Export as **Markdown**, **CSV**, or **JSON**
|
||
- 🔍 Optionally include **full subscription details** (e.g., cycle, auto-renew, currency)
|
||
- 🗃 Output to a custom file
|
||
- 🧼 Modular, readable Bash script using secure temp file handling
|
||
- 🧰 Lightweight, portable, and dependency-minimal (requires `curl` and `jq`)
|
||
|
||
---
|
||
|
||
## 🚀 Installation
|
||
|
||
```bash
|
||
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**:
|
||
```bash
|
||
sudo apt install curl jq
|
||
```
|
||
|
||
- **macOS (Homebrew)**:
|
||
```bash
|
||
brew install curl jq
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Usage
|
||
|
||
```bash
|
||
./wallos-fetch.sh [options]
|
||
```
|
||
|
||
> ℹ️ This script requires `curl` and `jq`. Run `./wallos-fetch.sh --help` to see all 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)
|
||
|
||
```markdown
|
||
# 🧾 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.
|
||
|
||
```csv
|
||
"id","name","price","next_payment","category_name","payment_method_name"
|
||
"1","Netflix","17.99","2025-04-21","Entertainment","Credit Card"
|
||
"2","Spotify","9.99","2025-05-01","Music","PayPal"
|
||
```
|
||
|
||
### 📦 JSON
|
||
|
||
Raw response data from the Wallos API—useful for backups, custom reporting, or integrations.
|
||
|
||
```json
|
||
{
|
||
"subscriptions": [
|
||
{
|
||
"id": 1,
|
||
"name": "Netflix",
|
||
"price": 17.99,
|
||
"currency_id": "USD",
|
||
"next_payment": "2025-04-21",
|
||
"category_name": "Entertainment",
|
||
"payment_method_name": "Credit Card"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
API_KEY="${API_KEY:-$WALLOS_API_KEY}"
|
||
```
|
||
|
||
with:
|
||
|
||
```bash
|
||
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](https://www.gnu.org/licenses/gpl-3.0.html).
|
||
|
||
---
|
||
|
||
## 🤝 Contributions
|
||
|
||
Feedback, bug reports, and pull requests are welcome!
|
||
Submit issues or improvements via the 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
|