Dx Org Trial Expiration Check

Org Expiration Check

Determine when a Salesforce org expires, how many days remain, and whether it has already expired — for one org, the default org, or every authenticated org. Results are prioritized (already-expired and soonest-expiring first) with a one-line summary. The skill can also emit machine-readable output for alerting, print backup commands for an at-risk org, and explain how to renew an expiring trial or Developer Edition org.

When to use

Trigger on requests like:

• "When does my trial org expire?" / "Is it still active or has it expired?"
• "How many days are left on my trial?"
• "Which of my orgs are expiring soon?" / "expiring within 30 days?"
• "Alert me / set up a cron job for expiring orgs" (use --json + --fail-if-expiring).
• "Back up my org before it expires" (use --preserve).
• "How do I extend / renew my trial (or Developer Edition) org?" (use --renew).

This skill covers trial editions, Developer Edition orgs (anything with a TrialExpirationDate), and scratch orgs (via the expirationDate from sf org list).

When NOT to use

Do not trigger this skill for:

• Sandbox refresh timing — that is not an expiration date.
• Creating, deleting, or switching orgs — this skill only reads expiration and prints guidance; it never creates, deletes, refreshes, or changes the active/default org. (To switch the default org, use dx-org-switch.)
• Non-Salesforce trials — e.g. AWS free tier, Netflix, or any other vendor's trial. This skill is Salesforce-only.

How expiration is determined

• Trial / Developer Edition orgs: the authoritative source is the org's Organization.TrialExpirationDate field, read via SOQL (sf data query). This field is null for paid/production orgs, which therefore report no trial expiration — that is expected, not an error.
• Scratch orgs: the expirationDate reported by sf org list (no SOQL query is issued for scratch orgs).

Steps

1. CRITICAL: Run the bundled helper script, which handles date math (days remaining, expired, expiring-soon warnings), prioritized sorting, and structured output, and works on macOS and Linux. Always invoke it by absolute path from the skill directory — never ./scripts/, which resolves against the user's current directory and will either run the wrong script or fail.

   Before executing, verify:

   • <skill_dir> is an absolute path (starts with /), not a relative path
   • The path points at this skill's own directory (the one containing this SKILL.md)

   bash "<skill_dir>/scripts/check_expiration.sh" <alias-or-username>   # one org
   bash "<skill_dir>/scripts/check_expiration.sh"                       # default org (target-org config)
   bash "<skill_dir>/scripts/check_expiration.sh" --all                 # every authenticated org
   bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30     # only orgs expiring within 30 days

   <skill_dir> is the absolute path to the directory containing this SKILL.md.

2. Relay the script output to the user. When an org could not be queried, surface the sf org login web command the script prints so the user can authenticate. Pick optional flags based on what the user asked for (see below): --preserve when they want to save their work, --renew when they ask how to extend, --json/--csv for automation, --fail-if-expiring for a cron/CI gate.

Options

Flag order is flexible and flags combine (e.g. --all --within 30 --json).

Prioritized output

Human output is grouped by urgency — Expired first, then Expiring soon (within 7 days, flagged Warning), then Active, then No trial expiration, then any orgs that could not be queried — and ends with a one-line summary:

Org expiration status for all authenticated orgs:

Expired:
  old-trial                       trial/DE edition expired 2026-06-20  (EXPIRED 19 day(s) ago)

Expiring soon (within 7 day(s)):
  almost-up                       trial/DE edition expires 2026-07-14  (expires in 5 day(s)  Warning)

Active (not expiring soon):
  acme-trial                      trial/DE edition expires 2026-08-15  (expires in 37 day(s))
  my-scratch                      scratch org expires 2026-07-25  (expires in 16 day(s))

No trial expiration (paid/production):
  prod                            no trial expiration (paid/production org)

Summary: 1 expired, 1 expiring within 7 day(s), 2 active, 1 with no expiration.

Structured output for alerting and cron (--json / --csv)

For dashboards, spreadsheets, or scheduled jobs, use --json or --csv to get machine-readable records (no prose). Each record has org, kind, expirationDate, daysRemaining (negative = expired, null = no expiration), status, and orgId. This is deterministic and needs no LLM in the loop.

# JSON, filtered to orgs expiring within 30 days:
bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30 --json

Cron watchdog — --fail-if-expiring[=N] exits 3 (and prints an ALERT: line to stderr) if any org expires within N days (default 7), so a scheduled job can page you before an org lapses:

# crontab: every morning at 9, alert if anything expires within 7 days
0 9 * * *  bash "<skill_dir>/scripts/check_expiration.sh" --all --fail-if-expiring 7 \
             || mail -s "Salesforce org expiring soon" me@example.com

Preserve your work before an org lapses (--preserve)

When an org expires you lose access to its metadata and data. --preserve prints ready-to-run backup commands (metadata manifest + retrieve, and a bulk data export) for each expiring or already-expired org. It only prints the commands — review and run them yourself:

bash "<skill_dir>/scripts/check_expiration.sh" my-trial --preserve