| 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
- Run
python3 ~/.agents/skills/wallos/scripts/wallos-api.py list
- Parse JSON response
- 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
- Fetch all subscriptions with
list
- Calculate monthly/yearly totals
- Group by category for breakdown
- Identify most expensive subscriptions
- 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)