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