subtrack

Appearance

Usage Guides ​

Practical workflows for managing your subscriptions with subtrack. The guide is grouped by task — start with the category that matches what you want to do, or search for a command name.

Managing subscriptionsAdd, edit, pause, cancel, clone, and clean up subscriptions.First-time setup & adding subscriptions · Editing subscriptions · Pausing, resuming, and renewing · Cancelling with the guided checklist · Cloning subscriptions · Archiving and unarchiving · Bulk operations · Finding duplicates · Reusable templates · Subscription suggestions · Tracking free trialsSpending & budgetsUnderstand totals, plan budgets, and forecast future costs.Tracking upcoming bills · Analytics and budget tracking · Budgets and yearly reports · Understanding your spending · Managing multi-currency subscriptions · Spending forecast · Cost optimization · Comparing spending over time · Monthly spending timeline · Price change history · Reviewing what's coming upOrganizing & searchingTags, search, imports, and saved filter profiles.Importing from CSV · Tag-based organization · Searching subscriptions · Filter profilesData & maintenanceExports, backups, audits, and integrity checks.Exporting data · Regular backups · Audit trail · Database maintenance · Database statistics · Data integrity and change historyLLM API usageTrack, import, and refresh API costs.Tracking LLM API costsDisplay & alertsThemes, columns, and desktop notifications.Calendar view · Desktop notifications · Customizing the displayIntegrationsConnect subtrack to AI assistants.MCP integration

Managing subscriptions ​

Add, edit, pause, cancel, clone, and clean up subscriptions.

First-time setup & adding subscriptions ​

After installation, start by adding your subscriptions. Each subscription needs a name, price, currency, billing cycle, and status:

bash
subtrack add \
  --name Netflix \
  --price 14.99 \
  --currency USD \
  --cycle monthly \
  --status active

Once added, verify with:

bash
subtrack list

Example: Adding a Netflix subscription ​

bash
subtrack add \
  --name "Netflix Premium" \
  --price 1980 \
  --currency JPY \
  --cycle monthly \
  --status active \
  --tags "video,entertainment"

Editing subscriptions ​

Update existing subscriptions with subtrack edit. Specify the subscription ID and the fields to update — only the passed fields change:

bash
subtrack edit 3 --price 2500 --tags "video,entertainment,4k"

To see subscription IDs, run subtrack list. Editing without an ID — or without any field flag — takes no action.

Managing status and billing day ​

Each subscription has a status (active, paused, cancelled, archived) and an optional billing day (day of month).

bash
# Pause a subscription (excluded from totals and upcoming bills)
subtrack edit 3 --status paused

# Set a specific billing day for accurate upcoming bill predictions
subtrack edit 3 --billingDay 15

# Reactivate a paused subscription
subtrack edit 3 --status active

Paused subscriptions are preserved in the database but excluded from payment calculations. Cancelled subscriptions are kept for record-keeping but excluded from all totals.

Pausing, resuming, and renewing ​

subtrack edit --status works, but the dedicated commands are faster for multiple IDs:

bash
# Pause one or more subscriptions
subtrack pause 3
subtrack pause 3 5 --force

# Bring a paused or cancelled subscription back to active
subtrack resume 3 --force

# Renew with a new price and contract end date (recorded in price history)
subtrack renew 3 --price 1980 --contractEnd 2027-08-31

--force skips the confirmation prompt, which makes these safe to script.

Cancelling with the guided checklist ​

subtrack cancel reviews the cancellation steps (optional data export, alternative-service checks, a cancellation-date note, and a final confirmation) and aborts without changes until you pass --force. With --force, the subscription is marked cancelled (not deleted) and written to the audit log.

bash
# Preview the cancellation without changing anything
subtrack cancel 3

# Cancel immediately (cron / scripting)
subtrack cancel 3 --force

# Inspect the target subscription as JSON (no changes made)
subtrack cancel 3 --json

To remove a cancelled subscription permanently, use subtrack delete <id>.

Cloning subscriptions ​

Clone an existing subscription to quickly create a similar one:

bash
# Clone subscription 3 with auto-generated name
subtrack clone 3

# Clone with custom name and price override
subtrack clone 3 --name "Netflix (Travel)" --price 1500

All fields from the source subscription are copied. Use optional flags to override specific fields.

Archiving and unarchiving ​

Archive subscriptions you no longer actively use but want to keep for reference:

bash
# Archive a subscription
subtrack archive 5

# Restore it when needed
subtrack unarchive 5

Archived subscriptions are excluded from all payment calculations and reports, unlike cancelled subscriptions which are kept for record-keeping without a path back to active.

Bulk operations ​

Manage multiple subscriptions at once with filters:

bash
# Pause all unused subscriptions
subtrack bulk status --set paused --tag unused

# Delete cancelled subscriptions
subtrack bulk delete --status cancelled

# Tag all active music subscriptions
subtrack bulk tag add --add music --status active

Finding duplicates ​

subtrack dedupe compares normalized subscription names for near-matches (Levenshtein distance, default threshold 0.8; pairs sharing a vendor URL are boosted):

bash
subtrack dedupe
subtrack dedupe --threshold 0.7
subtrack dedupe --json

# Merge the duplicate (price history and tags move to the kept entry)
subtrack dedupe merge 4 5

Reusable templates ​

Save a frequently used subscription shape once, then create instances from it:

bash
subtrack template add spotify --price 980 --currency JPY --cycle monthly --tags music
subtrack template list

# Create a subscription from the template
subtrack template use spotify

# Override fields at creation time
subtrack template use spotify --price 1080

subtrack template edit spotify --price 1080
subtrack template delete spotify

Subscription suggestions ​

Suggestions are candidate subscriptions detected by the scanner (for example AI tool usage that looks like a paid plan) or imported from a receipt file:

bash
# List pending candidates
subtrack suggest list
subtrack suggest view 3

# Accept a candidate
subtrack suggest add 3

# Dismiss one, or all
subtrack suggest dismiss 3
subtrack suggest dismiss --all

subtrack receipt <file> parses a receipt and creates candidates; use --dryRun to inspect without writing.

Tracking free trials ​

Add trial periods to get reminders before they expire:

bash
# Add a trial
subtrack trial add --name "Spotify Premium" --expires-at 2026-08-01 --price 980 --currency JPY --cycle monthly

# List all trials
subtrack trial list

# See what's expiring soon
subtrack trial expiring 7

Spending & budgets ​

Understand totals, plan budgets, and forecast future costs.

Tracking upcoming bills ​

See which subscriptions are due for payment soon:

bash
# Bills due in the next 7 days (default)
subtrack upcoming

# Bills due in the next 30 days
subtrack upcoming 30

# Bills due today
subtrack upcoming 0

The upcoming command uses each subscription's billingDay (or creation date) to calculate the next billing date. Only active and paused subscriptions are included.

Analytics and budget tracking ​

Get detailed analytics including status breakdown and budget tracking:

bash
subtrack analytics

Set a monthly budget to track spending:

bash
subtrack config set monthlyBudget 500
subtrack analytics

The analytics command shows whether you're within budget or over.

Budgets and yearly reports ​

Set a budget and check it against actual spending:

bash
# Monthly budget
subtrack config set monthlyBudget 5000
subtrack budget

# Yearly budget, with a cron-friendly exit code
subtrack config set yearlyBudget 60000
subtrack budget --period yearly --check

# Named budgets (JSON array — amount, currency, optional period/categories)
subtrack config set budgets '[{"name":"streaming","amount":3000,"currency":"JPY","categories":["video","music"]}]'
subtrack budget --name streaming

--check exits with code 1 when spending exceeds the budget, which makes it usable as a cron guardrail.

For a full yearly breakdown, use subtrack report (or its alias subtrack yearly):

bash
subtrack report
subtrack report --year 2025
subtrack report --year 2025 --currency USD
subtrack report --year 2025 --json

The report shows total spending, a monthly bar chart, top subscriptions, what was added or cancelled during the year, price changes, and a comparison against yearlyBudget.

Understanding your spending ​

Use subtrack payment to see your total spending across different periods:

bash
# How much per month?
subtrack payment

# How much per year?
subtrack payment yearly

# Weekly cost in USD
subtrack payment weekly --currency USD

payment automatically converts all billing cycles to the target period. A yearly subscription will be divided into monthly cost, and a weekly subscription will be multiplied accordingly.

You can also include LLM API usage costs in the payment calculation:

bash
# Monthly subscription + API costs
subtrack payment monthly --api

# API costs converted to JPY
subtrack payment monthly --api --currency JPY

Summary statistics ​

Get a quick overview of all your subscriptions:

bash
subtrack summary

This shows total count, the most expensive subscription, monthly spending broken down by currency, and monthly spending broken down by tag.

Managing multi-currency subscriptions ​

If you have subscriptions in different currencies (e.g., JPY for local services and USD for international ones), subtrack handles this natively:

bash
# See everything in your local currency
subtrack list --currency JPY

# Compare spending across currencies
subtrack list

Without --currency, subscriptions are grouped by their original currency with per-group subtotals.

Spending forecast ​

Project your subscription costs into the future:

bash
# 12-month forecast
subtrack forecast

# What if I cancel Netflix?
subtrack forecast --cancel Netflix

# What if I add a new service?
subtrack forecast --addName "New Service" --addPrice 1500 --addCurrency JPY --addCycle monthly

Cost optimization ​

Let subtrack analyze your subscriptions for savings:

bash
# Show all optimization suggestions
subtrack optimize

# Only show suggestions saving $100+/year
subtrack optimize --min-savings 100

The optimizer flags:

  • Cycle changes — switching from monthly to yearly could save money
  • Duplicate subscriptions — similar services with overlapping features
  • Inactive subscriptions — paused or long-unused subscriptions
  • Cancelled waste — subscriptions that were cancelled but had recent payments

Comparing spending over time ​

See how your costs have changed between periods:

bash
# Current month vs last month
subtrack compare

# Current quarter vs last quarter
subtrack compare quarterly

The compare command accounts for price changes recorded in your subscription history.

Monthly spending timeline ​

Visualize spending trends:

bash
# 12-month view
subtrack timeline

# 6-month view with category breakdown
subtrack timeline --months 6 --categories

Price change history ​

Track when subscription prices changed:

bash
# History for a specific subscription
subtrack history 3

# All recent changes
subtrack history --all --days 30

Reviewing what's coming up ​

subtrack review combines upcoming bills, contract expirations, and expiring trials into one screen:

bash
subtrack review
subtrack review --billDays 30 --contractDays 60 --trialDays 14
subtrack review --json

Organizing & searching ​

Tags, search, imports, and saved filter profiles.

Importing from CSV ​

Bulk-import subscriptions from a CSV file:

bash
subtrack import subscriptions.csv

The CSV must have the header name,cycle,tags,price,currency (an optional notes column is also accepted; CSVs produced by subtrack export csv work as-is). Tags are separated by semicolons:

csv
name,cycle,tags,price,currency
Netflix,monthly,video;entertainment,1980,JPY
GitHub Copilot,monthly,development,10,USD

Use --dry-run to validate without importing:

bash
subtrack import subscriptions.csv --dry-run

Tag-based organization ​

Tags are a powerful way to categorize subscriptions. Examples:

  • By category: music, video, cloud, productivity
  • By priority: essential, nice-to-have
  • By payment method: credit-card, paypal
  • By usage: personal, work, family

Filter by tags:

bash
# Find all music-related subscriptions
subtrack tags music

# Find subscriptions used for both work and personal
subtrack tags work personal

Tags use AND logic — only subscriptions matching all specified tags are shown.

Managing tags ​

View all tags and their usage count:

bash
subtrack tag list

Rename a tag (merges if the new name already exists):

bash
subtrack tag rename entertainment fun

Delete a tag and its associations:

bash
subtrack tag delete fun

Clean up orphaned tags (tags no longer attached to any subscription):

bash
subtrack tag prune

Searching subscriptions ​

Quickly find subscriptions by name, notes, or tags:

bash
# Search by keyword
subtrack search netflix

# Search in notes only
subtrack search "family plan" --notes

Filter profiles ​

Save and switch between filter profiles to focus on specific subscription groups:

bash
# Save a "work" profile
subtrack profile save work --tag work --status active

# Switch to work profile
subtrack profile switch work

# Deactivate it again (also clears it when active)
subtrack profile delete work

# List saved profiles
subtrack profile list

Data & maintenance ​

Exports, backups, audits, and integrity checks.

Exporting data ​

Export subscriptions for use in spreadsheets or other tools:

bash
# CSV (for Excel / Google Sheets)
subtrack export csv

# JSON (for programmatic use)
subtrack export json

# Markdown (for documentation)
subtrack export md

# Filter by tags and convert currency
subtrack export csv --tags video --currency JPY

Regular backups ​

Set up a cron job (or Task Scheduler on Windows) for automatic backups:

bash
# Example cron: daily backup at 3 AM
0 3 * * * subtrack backup ~/subtrack-backups

Backups are timestamped and will never overwrite previous files. See Data & Storage for restore instructions.

Audit trail ​

Track all changes made to your subscription data:

bash
# View recent audit entries
subtrack audit list

# Filter by action type
subtrack audit list --action subscription.edit

# Prune old entries
subtrack audit prune --days 90

Database maintenance ​

Keep your database healthy with regular maintenance:

bash
# Integrity check only
subtrack maintenance

# Full maintenance with VACUUM
subtrack maintenance --vacuum

# One-command cleanup (integrity check + VACUUM + prune audit + prune tags)
subtrack cleanup

Database statistics ​

Get a quick overview of your database's health and contents:

bash
subtrack stats

Shows subscription counts by status, tag count, trial count, usage entry count, database file size, and price range information.

Data integrity and change history ​

bash
# Check for data problems (exits 1 with --strict)
subtrack check
subtrack check --strict

# Review what changed and when
subtrack changes --from 2026-01-01 --to 2026-12-31
subtrack changes --id 3

LLM API usage ​

Track, import, and refresh API costs.

Tracking LLM API costs ​

subtrack can track LLM API usage costs alongside subscription costs. This is useful if you use paid LLM APIs (OpenAI, Anthropic, etc.) and want to see total AI spending.

Adding usage entries ​

bash
subtrack usage add \
  --provider openai \
  --model gpt-4o \
  --input-tokens 5000 \
  --output-tokens 1500 \
  --date 2026-06-19 \
  --description "Code review"

Cost is automatically calculated using LiteLLM pricing data. If the model has no known pricing (or you are offline), pass --cost explicitly — for example --cost 0.50 for 50 USD cents.

Listing and filtering ​

bash
# All entries
subtrack usage list

# Filter by provider and date range
subtrack usage list --provider anthropic --from 2026-06-01

Including API costs in payment totals ​

bash
# See subscription + API costs together
subtrack payment monthly --api

API costs for the current period are fetched and added to the subscription totals. They are stored in USD cents and automatically converted if you use --currency.

Auto-scanning from AI tools ​

subtrack can automatically discover and import LLM usage data from various AI coding tools:

bash
# Auto-scan known sources for the current month
subtrack usage refresh

# Scan a specific date range
subtrack usage refresh --from 2026-01-01 --to 2026-06-30

# Scan all available historical data
subtrack usage refresh --all

Supported sources: OpenCode DB, Claude Code, Codex CLI, Cursor, GitHub Copilot, and Windsurf.

Importing from log files ​

Import usage data from provider response logs:

bash
# Import from a JSONL file
subtrack usage import ./openai-responses.jsonl

# Pipe from stdin
cat responses.jsonl | subtrack usage import -

Refreshing pricing data ​

The LiteLLM pricing cache is automatically refreshed every 24 hours. To force a refresh:

bash
subtrack usage refresh

Display & alerts ​

Themes, columns, and desktop notifications.

Calendar view ​

See which days of the month have bills due:

bash
# Current month
subtrack calendar

# Specific month
subtrack calendar --month 12 --year 2026

Desktop notifications ​

Get OS-level reminders for upcoming bills:

bash
# Preview upcoming bills
subtrack notify --dry-run

# Send notification
subtrack notify

# Custom look-ahead period
subtrack notify --days 3

Customizing the display ​

subtrack's tables and headings are themeable via subtrack config set. Everything is stored in config.json and validated on write, so an invalid value never breaks your terminal.

Choosing a theme preset ​

The theme key picks a preset tuned for your terminal:

bash
# Dark terminal backgrounds (default)
subtrack config set theme default

# Light terminal backgrounds
subtrack config set theme light

# Maximum contrast for accessibility or bright environments
subtrack config set theme high-contrast

# Plain monochrome — ideal for piping output or screen readers
subtrack config set theme none

Overriding individual colors ​

Any color key overrides the active preset. Valid color names are black, red, green, yellow, blue, magenta, cyan, white, gray, plus the bright* variants (brightRed, brightGreen, ...).

bash
# Accent color used for section headings
subtrack config set accentColor brightCyan

# Table chrome: border, header, and zebra stripe background
subtrack config set tableBorderColor blue
subtrack config set tableHeaderColor brightBlue
subtrack config set tableZebraColor gray

Table sizing and zebra stripes ​

bash
# Turn zebra striping off (or back on)
subtrack config set tableZebra off

# Minimum table width in columns (20–200); tables still grow
# to fit the terminal width when content requires it
subtrack config set tableMinWidth 60

Dates and list columns ​

bash
# Compact MM/DD dates in cancel/notify messages
# (JSON output always stays ISO 8601)
subtrack config set dateFormat short

# Show notes / payment method columns in `subtrack list` by default
subtrack config set listShowNotes on
subtrack config set listShowMethod on

CLI flags (subtrack list --notes --method) always take precedence over these defaults.

Seeing the current configuration ​

bash
subtrack config list

Integrations ​

Connect subtrack to AI assistants.

MCP integration ​

subtrack runs an MCP (Model Context Protocol) server, allowing AI assistants to manage your subscriptions:

bash
subtrack mcp

This enables AI tools like Claude Desktop, Cursor, and Windsurf to read and modify your subscription data. See the MCP page for setup instructions and tool reference.

Released under the MIT License.

Copyright © 2025-present nazozokc