Get started fast. Go deep when you need to.

5-minute quick start

Try this in any Node.js repo — React, Next.js, Express, or a plain TypeScript monorepo.

1. Try it in 30 seconds (no repo needed)

   npm install -g expiry && expiry demo

   Creates a sample expiry-demo/ folder with annotated files and runs an offline scan.

2. Install the CLI

   npm install -g expiry

3. Tag one piece of temporary code

   Put a comment on the line above the hack. The format is: condition, then a short note.

   // @expiry date:2026-12-31 | remove holiday banner
   function showHolidayBanner() {
     return true;
   }

4. Scan your project

   expiry scan -p .

   Expiry lists every @expiry comment and whether it is pending, ready to remove, or overdue.

5. Check your health score

   expiry stats --offline

6. Add CI (optional)

   expiry init

   Creates .expiry.json and a GitHub Actions workflow. See CI setup below.

How it works

Traditional TODOs say when to delete code (“after Q3”). Expiry ties deletion to a condition your CI can verify — a closed ticket, an upgraded dependency, a removed env var.

Annotation format

// @expiry <condition> | <human note> | owner:team (optional)

• Condition — machine-readable signal (see conditions)
• Note — what to remove and why (for humans in code review)
• Pipe | — combine conditions: remove when any is satisfied

Tag temporary code

Single-line (most common)

One comment above the code you plan to delete:

// @expiry issue:ENG-442:closed | remove legacy auth prefix
export function legacyAuth(token: string) {
  return token.startsWith("legacy_");
}

Real-world examples

// @expiry issue:ENG-442:closed | drop v1 webhook handler

// @expiry dep:react@>=19.0.0 | remove React 18 shim

// @expiry flag:NEW_UI:enabled | delete old layout branch

// @expiry env:LEGACY_CHECKOUT! | remove old checkout path

// @expiry-block issue:ENG-100:closed | remove legacy module
function legacyA() {}
function legacyB() {}
// @expiry-end

Conditions

Pick the signal that means “this hack can go.” Combine with | — Expiry marks ready when any condition is satisfied.

CLI commands

All commands accept -p <path> for the repo root (defaults to current directory).

expiry scan -p . --offline
expiry check -p .
expiry report -p . --format sarif -o expiry.sarif

CI setup

Quick setup

1. Run expiry init in your repo root
2. Commit .expiry.json and .github/workflows/expiry.yml
3. Add EXPIRY_LICENSE_KEY to GitHub Actions secrets (free tier works without a key for scan/check)
4. Tag temporary code with @expiry comments and open a PR — the workflow runs automatically

GitHub Actions workflow

Generated by expiry init, or add manually:

name: Expiry
on:
  pull_request:
  push:
    branches: [main]

jobs:
  expiry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g expiry
      - run: expiry check -p .
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          EXPIRY_LICENSE_KEY: ${{ secrets.EXPIRY_LICENSE_KEY }}

Configuration

.expiry.json in your repo root (created by expiry init):

{
  "gracePeriodDays": 7,
  "issueProvider": "auto",
  "github": { "owner": "your-org", "repo": "your-repo" },
  "jira": {
    "baseUrl": "https://your.atlassian.net",
    "email": "you@company.com"
  }
}

Environment variables

Pro features

Free tier covers scan, check, validate, and CI gating. Pro and Team add automation after conditions are met:

• Auto-cleanup PRs — draft PR with code removal when ready
• Slack & email alerts — notify owners when debt is overdue
• SARIF export — feed findings into GitHub Advanced Security
• Jira sync — link annotations to tickets

export EXPIRY_LICENSE_KEY="your_key_from_dashboard"
expiry cleanup --dry-run -p .
expiry pr --draft -p .
expiry notify -p .

Compare Free, Pro, and Team → · Get your license key →

Troubleshooting

More questions? See the FAQ or how it works overview.