wallos

name	wallos
description	Manage personal subscriptions via Wallos (self-hosted tracker). Use when the user asks to view, add, edit, or delete subscriptions, check spending, manage categories/payment methods, or anything related to subscription tracking and recurring expenses.

Wallos Subscription Manager

Interact with the user's self-hosted Wallos instance to manage subscriptions, categories, payment methods, and spending analytics.

Configuration

Set these environment variables before using the skill:

export WALLOS_URL="https://your-wallos-instance.com"
export WALLOS_API_KEY="your-api-key-here"

• Auth: API key passed as api_key query parameter (GET) or form field (POST)
• Generate your API key in Wallos: Settings → API

Quick Reference

Run the helper script for any Wallos operation:

python3 ~/.agents/skills/wallos/scripts/wallos-api.py <action> [args...]

Available Actions

Action	Description	Example
list	List all subscriptions	python3 ~/.agents/skills/wallos/scripts/wallos-api.py list
list --active	Active subscriptions only	python3 ~/.agents/skills/wallos/scripts/wallos-api.py list --active
list --sort price	Sort by price	python3 ~/.agents/skills/wallos/scripts/wallos-api.py list --sort price
categories	List all categories	python3 ~/.agents/skills/wallos/scripts/wallos-api.py categories
payments	List payment methods	python3 ~/.agents/skills/wallos/scripts/wallos-api.py payments
currencies	List currencies	python3 ~/.agents/skills/wallos/scripts/wallos-api.py currencies
household	List household members	python3 ~/.agents/skills/wallos/scripts/wallos-api.py household
stats	Spending summary	python3 ~/.agents/skills/wallos/scripts/wallos-api.py stats
upcoming	Next 30 days payments	python3 ~/.agents/skills/wallos/scripts/wallos-api.py upcoming

Output

The script returns structured JSON. Parse and present results in a user-friendly format with tables or bullet points.

Workflow

Viewing Subscriptions

1. Run python3 ~/.agents/skills/wallos/scripts/wallos-api.py list
2. Parse JSON response
3. Present as a formatted table with name, price, next payment, category, status

Adding a Subscription

Adding requires session authentication (username/password login via /login.php). The API key alone is read-only for subscription mutations.

For now, guide the user to add subscriptions via the Wallos Web UI.

Spending Analysis

1. Fetch all subscriptions with list
2. Calculate monthly/yearly totals
3. Group by category for breakdown
4. Identify most expensive subscriptions
5. Flag upcoming payments in the next 7/30 days

API Details

For full API endpoint documentation, read: ~/.agents/skills/wallos/reference/api-endpoints.md

Important Notes

• API key provides read-only access to GET endpoints
• Write operations (add/edit/delete subscriptions) require session authentication
• Currency amounts are in their original currency; use convert_currency=true for main currency
• Dates are in YYYY-MM-DD format
• Cycle values: 1=daily, 2=weekly, 3=monthly, 4=yearly
• Frequency is a multiplier (e.g., cycle=3, frequency=3 = quarterly)