SubsTracker

Manage SubsTracker subscriptions and configuration via CLI scripts. Handles login, subscription CRUD, config updates, notifications, and dashboard queries. U...

Security Scan

The skill's code matches its stated purpose (a CLI wrapper for a SubsTracker REST API) but metadata and runtime instructions are inconsistent and it will read/write local secrets and auto-login against an arbitrary SUBSTRACKER_URL; review before installing or granting it access to credentials.

Purpose & Capability

The scripts implement a CLI client for a SubsTracker REST API (login, subscription CRUD, payments, config, notifications, dashboard). That capability aligns with the skill name and description. However the registry metadata lists no required environment variables or primary credential while the skill actually requires SUBSTRACKER_URL, SUBSTRACKER_USER, and SUBSTRACKER_PASS — a clear metadata omission (incoherence between declared requirements and actual needs).

Instruction Scope

Runtime instructions and code auto-load credentials from environment or .substracker-skills/.env (cwd or home), perform automatic login, and write a cookie to ~/.substracker-skills/cookie. The SKILL.md also instructs the platform to invoke this skill whenever the user mentions subscriptions (very broad trigger). The code will send credentials to whatever SUBSTRACKER_URL is configured and can POST config updates including admin passwords, webhook URLs, and notification tokens. Reading/writing dotfiles and auto-logging in are expected for a CLI client but these actions access sensitive data and are broader than what the registry metadata advertises.

Install Mechanism

No install spec is provided (instruction-only). The code is included in the skill bundle and expects to be run with bun (or npx -y bun). There is no external download or archive extraction in the manifest, so installation risk is low from an installer perspective.

Credentials

The code requires SUBSTRACKER_URL, SUBSTRACKER_USER, and SUBSTRACKER_PASS to operate and will read those from system env or .env files; however the registry declares no required env vars or primary credential. The skill also accepts many configuration flags that map to secret fields (tokens, webhook URLs, email API keys, etc.). Requesting and sending these secrets is coherent with the purpose but the metadata omission and the number of secret-capable fields mean you should only provide credentials for a trusted SubsTracker instance.

Persistence & Privilege

The skill does not request 'always: true' and does not alter other skills. It will create and write a cookie file under ~/.substracker-skills and may create ~/.substracker-skills/.env if the user follows instructions; this is expected for a CLI client but constitutes persistent local state that contains session data and should be considered sensitive.

What to consider before installing

This skill appears to be a legitimate CLI wrapper for a SubsTracker REST API, but exercise caution before enabling it: - The skill requires SUBSTRACKER_URL, SUBSTRACKER_USER, and SUBSTRACKER_PASS at runtime, but the registry metadata doesn’t declare those — confirm you are comfortable providing those credentials and that the registry omission is acceptable. - It will read .env files from the current working directory and from your home directory and will write a cookie file to ~/.substracker-skills/cookie. Ensure those locations don’t unintentionally contain other secrets and that storing a session cookie on disk is acceptable. - The tool will send credentials and can update sensitive config fields (admin password, webhook URLs, notification tokens). Only point it at a SubsTracker server you trust (check the SUBSTRACKER_URL). - The SKILL.md suggests invoking this skill on any user mention of subscriptions (a very broad trigger). If you want to avoid accidental use, restrict invocation or require explicit user confirmation before running commands that access credentials or change config. - Because the source/homepage are unknown, prefer to: (a) request the upstream repository or signed publisher info, (b) review the files yourself (they are included), or (c) run the scripts in an isolated environment/container before giving it real credentials. If you trust the SubsTracker instance and accept the local file writes, the code appears coherent with its stated purpose; otherwise, treat it as suspicious until metadata (required envs, source) and invocation behavior are clarified.

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):

1. System environment variables
2. <cwd>/.substracker-skills/.env
3. ~/.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: false and message explaining what went wrong