@keepmysubs/cli

@keepmysubs/cli

kms — the command-line client for KeepMySubs. List subscriptions, track spend and renewals, triage alerts, and parse inbound bills from your terminal or a cron job.

Install

npm install -g @keepmysubs/cli
# or run without installing:
npx @keepmysubs/cli --help

Authentication

The simplest way to log in is the browser flow — just run:

kms auth login

This opens a page in your browser where you can sign in (or sign up if you don't have an account yet) and authorize the CLI. A scoped API key is then minted and saved to your config file automatically. If the browser doesn't open, the command prints a URL you can paste in manually.

kms auth status                       # shows the stored key prefix
kms auth logout                       # forgets the stored key

For headless environments or CI where no browser is available, pass an API key directly. Create one at Settings → API keys in the KeepMySubs web app:

kms auth login --key kms_live_xxx     # validate and store the key, no browser

…or, for cron jobs and fully unattended automation, set the key in the environment (no config file needed):

export KMS_API_KEY=kms_live_xxx
kms renewals --next 7

Resolution order: KMS_API_KEY env var first, then the stored config file ($XDG_CONFIG_HOME/keepmysubs/config.json). KMS_BASE_URL overrides the API base URL (defaults to https://keepmysubs.com).

Output

Commands print a human-readable table or key/value view by default. Add --json for machine-readable output — handy for scripting and piping into jq. --json is global, so it works before or after the subcommand:

kms renewals --next 7 --json | jq '.[].name'
kms --json subs ls

Exit codes

Code	Meaning
0	OK
1	Generic error
2	Usage error (bad flags/args)
3	Auth error (missing/invalid key)
4	Rate limited
5	Entitlement required (no active plan)
6	Possible duplicate (re-run subs add with --force)

Examples

# Subscriptions
kms subs ls --status active
kms subs show <id>
kms subs add "Vercel Pro" --price 20 --cycle monthly
kms subs update <id> --price 25
kms subs rm <id>

# Spend & renewals
kms spend
kms renewals --next 7 --json
kms charges --limit 20

# Alerts
kms alerts ls
kms alerts dismiss <id>

# Bills
kms bills pending
kms bills parse ./receipt.pdf
kms bills accept <id>
kms bills reject <id>