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
• /.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 /scripts/main.ts  [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 
bun scripts/main.ts s update  --amount 19.99
bun scripts/main.ts s delete 
bun scripts/main.ts s toggle  --active false
bun scripts/main.ts s renew  --amount 15.99 --note "March renewal"
bun scripts/main.ts s test-notify 

Subscription Flags (create / update)

Toggle Flags

Renew Flags

Payments

bun scripts/main.ts p list 
bun scripts/main.ts p edit   --amount 19.99 --note "adjusted"
bun scripts/main.ts p delete  

Payment Edit Flags

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

Test Notification

bun scripts/main.ts t --type telegram

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