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