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

Subscriptions

# List all
bun scripts/main.ts s list

# Create — name and expiry-date are required, everything else has sensible defaults
bun scripts/main.ts s create --name "Netflix" --expiry-date 2026-04-07 \
  --amount 15.99 --currency CNY --period-unit month --period-value 1 \
  --category "娱乐" --custom-type "视频流媒体" --reminder-value 3

# Read / Update / Delete
bun scripts/main.ts s get <id>
bun scripts/main.ts s update <id> --name "Netflix Premium" --amount 19.99
bun scripts/main.ts s delete <id>

# Toggle active/inactive
bun scripts/main.ts s toggle <id> --active false

# Manual renew (extend by one billing cycle)
bun scripts/main.ts s renew <id> --amount 15.99 --note "March renewal"

# Send test notification for a specific subscription
bun scripts/main.ts s test-notify <id>

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>

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 \
  --tg-bot-token "123:ABC" --tg-chat-id "987654"

Test Notification

bun scripts/main.ts t --type telegram

Supported types: telegram, notifyx, webhook, wechatbot, email, bark, gotify.

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