substracker

name

substracker

description

Manage SubsTracker subscriptions and configuration via CLI scripts. Handles login, subscription CRUD, config updates, notifications, and dashboard queries. Use this skill whenever the user mentions subscriptions, recurring payments, subscription tracking, renewal reminders, payment history, notification configuration (Telegram, Bark, email, webhook, Gotify), or anything related to their SubsTracker instance — even if they just say "add a subscription", "what am I paying for", "check my renewals", "how much do I spend monthly", "update my Telegram config", "加个订阅", "我订阅了什么", "有哪些快到期了", "每月花多少钱", "续费", "订阅提醒", "通知设置", "看下订阅", "账单" without explicitly mentioning SubsTracker.

SubsTracker API Skill

Manage subscriptions via CLI scripts that wrap the SubsTracker REST API. The scripts handle authentication, cookie management, and retries — you just call a command and get JSON back.

Skill Structure

substracker-skills/
├── SKILL.md              ← You are here
└── scripts/
    ├── main.ts           ← CLI entry point (routing only)
    ├── client.ts         ← HTTP client, env loading, auth
    ├── types.ts          ← TypeScript interfaces (canonical schema + docs)
    ├── subscriptions.ts  ← Subscription commands
    ├── payments.ts       ← Payment commands
    ├── config.ts         ← Config commands
    ├── dashboard.ts      ← Dashboard command
    └── notifications.ts  ← Notification test command

Read scripts/types.ts for all field names, types, defaults, and descriptions (TSDoc comments).

Configuration

Scripts auto-load credentials from .env files. No manual setup in the session.

Load priority (first found wins):

1. System environment variables
2. <cwd>/.substracker-skills/.env
3. ~/.substracker-skills/.env

Required variables in .env:

SUBSTRACKER_URL=https://sub.example.com
SUBSTRACKER_USER=admin
SUBSTRACKER_PASS=your_password

If variables are missing, the script exits with a clear error. Ask the user to create their .env file.

Running Commands

Resolve the runtime: use bun if installed, otherwise npx -y bun.

All commands follow the same pattern:

bun <SKILL_DIR>/scripts/main.ts <command> [subcommand] [--flags]

Scripts output JSON to stdout (for you to parse) and log to stderr (for debugging). Authentication and session cookies are handled automatically — if a session expires, the script re-logs in and retries.

Command Reference

Login

bun scripts/main.ts login

Usually not needed — all commands auto-login when no session exists. Use this to verify credentials.

Subscriptions

bun scripts/main.ts s list
bun scripts/main.ts s create --name "Netflix" --expiry-date 2026-04-07 --amount 15.99
bun scripts/main.ts s get <id>
bun scripts/main.ts s update <id> --amount 19.99
bun scripts/main.ts s delete <id>
bun scripts/main.ts s toggle <id> --active false
bun scripts/main.ts s renew <id> --amount 15.99 --note "March renewal"
bun scripts/main.ts s test-notify <id>

Subscription Flags (create / update)

Flag	Type	Required	Description
--name	string	create only	Subscription name
--expiry-date	string	create only	Expiration date (ISO format)
--amount	number	-	Cost per billing cycle
--currency	string	-	Currency code, default CNY
--period-unit	day|month|year	-	Billing cycle unit, default month
--period-value	number	-	Billing cycle length, default 1
--category	string	-	Category label (e.g. 娱乐)
--custom-type	string	-	Custom type (e.g. 视频流媒体)
--mode	cycle|reset	-	Subscription mode
--start-date	string	-	Start date (ISO format)
--auto-renew	true|false	-	Auto-renew flag, default true
--active	true|false	-	Active status
--reminder-unit	day|hour	-	Reminder unit
--reminder-value	number	-	Reminder value
--reminder-days	number	-	Reminder days before expiry
--lunar	true|false	-	Use lunar calendar
--notes	string	-	Notes / memo

Toggle Flags

Flag	Type	Description
--active	true|false	Set active or inactive

Renew Flags

Flag	Type	Description
--amount	number	Payment amount
--period-multiplier	number	Multiply billing cycle
--payment-date	string	Payment date
--note	string	Payment note

Payments

bun scripts/main.ts p list <sub-id>
bun scripts/main.ts p edit <sub-id> <payment-id> --amount 19.99 --note "adjusted"
bun scripts/main.ts p delete <sub-id> <payment-id>

Payment Edit Flags

Flag	Type	Description
--date	string	Payment date
--amount	number	Payment amount
--note	string	Payment note

Dashboard

bun scripts/main.ts d

Returns monthly/yearly spend, active count, upcoming renewals, expense breakdown.

Config

bun scripts/main.ts c get
bun scripts/main.ts c update --timezone Asia/Shanghai --notifiers telegram,bark

Config Flags

Flag	Type	Description
--username	string	Admin username
--password	string	Admin password
--timezone	string	Timezone (e.g. Asia/Shanghai)
--show-lunar	true|false	Show lunar calendar dates
--theme	string	Theme mode
--notifiers	string	Comma-separated: telegram,bark,email,webhook,wechatbot,gotify
--tg-bot-token	string	Telegram bot token
--tg-chat-id	string	Telegram chat ID
--bark-key	string	Bark device key
--bark-server	string	Bark server URL
--webhook-url	string	Webhook URL
--webhook-method	string	Webhook HTTP method
--webhook-template	string	Webhook body template
--wechat-webhook	string	WeChat bot webhook URL
--gotify-url	string	Gotify server URL
--gotify-token	string	Gotify app token
--email-from	string	Sender email
--email-to	string	Recipient email
--resend-key	string	Resend API key
--clear-secrets	string	Comma-separated fields to clear
--debug	true|false	Enable debug logs
--payment-history-limit	number	Max payment history entries

Test Notification

bun scripts/main.ts t --type telegram

Flag	Type	Required	Description
--type	string	✓	telegram|notifyx|webhook|wechatbot|email|bark|gotify
Other flags	-	-	Passed as config overrides (e.g. --tg-bot-token → TG_BOT_TOKEN)

Presenting Results

When showing subscription data to the user, format JSON responses as readable tables or summaries — don't dump raw JSON. For example, a subscription list should look like a table with name, amount, cycle, next renewal date, and status.

Error Handling

• Missing env vars: script exits with instructions to create .env
• 401 Unauthorized: auto re-login and retry (once)
• API errors: response includes success: false and message explaining what went wrong