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):
- System environment variables
<cwd>/.substracker-skills/.env~/.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: falseandmessageexplaining what went wrong