Manage SubsTracker subscriptions and configuration via CLI scripts. Handles login, subscription CRUD, config updates, notifications, and dashboard queries. U...
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.
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).
Scripts auto-load credentials from .env files. No manual setup in the session.
Load priority (first found wins):
<cwd>/.substracker-skills/.env~/.substracker-skills/.envRequired 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.
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.
bun scripts/main.ts login
Usually not needed — all commands auto-login when no session exists. Use this to verify credentials.
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>
| 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 |
| Flag | Type | Description |
|---|---|---|
--active | true|false | Set active or inactive |
| Flag | Type | Description |
|---|---|---|
--amount | number | Payment amount |
--period-multiplier | number | Multiply billing cycle |
--payment-date | string | Payment date |
--note | string | Payment note |
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>
| Flag | Type | Description |
|---|---|---|
--date | string | Payment date |
--amount | number | Payment amount |
--note | string | Payment note |
bun scripts/main.ts d
Returns monthly/yearly spend, active count, upcoming renewals, expense breakdown.
bun scripts/main.ts c get
bun scripts/main.ts c update --timezone Asia/Shanghai --notifiers telegram,bark
| 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 |
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) |
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.
.envsuccess: false and message explaining what went wrongZIP package — ready to use