docs: add project README with usage, licensing, and context.
This commit is contained in:
Nick Heppler
parent
086b66e557
commit
7517061922
146
README.md
146
README.md
@ -1,3 +1,145 @@
|
||||
# wallos-fetcher
|
||||
# 📦 Wallos Fetcher
|
||||
|
||||
Wallos Fetcher is a command-line tool designed for fetching and exporting subscription data from your Wallos instance. Wallos is an open-source personal subscription tracker, and this tool simplifies the process of retrieving and exporting your subscription details in various formats.
|
||||
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, 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
|
||||
|
||||
```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]
|
||||
```
|
||||
|
||||
### ✅ 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.
|
||||
|
||||
### 📦 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:
|
||||
|
||||
```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 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
|
||||
Loading…
Reference in New Issue
Block a user