Terminal
Terminal/Skill
Reports when Salesforce trial, Developer Edition and scratch orgs expire, with prioritized output for alerts and backup guidance.
By Salesforce
Works with
npx skills add forcedotcom/sf-skills --skill dx-org-trial-expiration-checkDetermine 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.
Trigger on requests like:
--json + --fail-if-expiring).--preserve).--renew).This skill covers trial editions, Developer Edition orgs (anything with a
TrialExpirationDate), and scratch orgs (via the expirationDate from
sf org list).
Do not trigger this skill for:
dx-org-switch.)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.expirationDate reported by sf org list (no SOQL
query is issued for scratch orgs).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 pathbash "<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.
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.
| Flag | Purpose |
|---|---|
--all, -a | Check every authenticated org. |
--within <days>, -w | Show only orgs expiring within N days (includes already-expired; omits paid/production). --within=30 also works. |
--json | Emit a JSON array of org records (data only). |
--csv | Emit CSV rows (data only). |
--preserve | Print backup commands for expiring/expired orgs. |
--renew | Print trial/DE extension & reactivation guidance. |
--fail-if-expiring[=N] | Exit 3 if any org expires within N days (default 7). |
--no-scratch | Exclude scratch orgs (trial/DE only). |
--help, -h | Show usage. |
Flag order is flexible and flags combine (e.g. --all --within 30 --json).
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.
--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)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
--renew)--renew prints the current guidance for keeping an org alive, and surfaces the
Org IDs of at-risk orgs so the steps are actionable:
partners.salesforce.com → Ask Agentforce → "I want to extend my Trial
Org", providing the Org ID. Eligible while active or expired < 30 days; not
for LDV orgs. (Salesforce Help article 000387818.)0 success1 an org could not be queried (auth/connection error)2 bad usage or a missing dependency (sf or jq)3 --fail-if-expiring threshold breached (at least one org expiring)When both apply, a --fail-if-expiring breach (3) takes precedence over an
auth error (1): the alerting signal wins so a watchdog still fires. If your
job must also detect unreachable orgs, run --json and inspect the records for
status: "auth_error" in addition to checking the exit code. Note that an org
whose credentials fail cannot be date-checked, so it never counts toward a
--fail-if-expiring breach on its own.
--fail-if-expiring with no explicit number treats a following all-numeric
argument as the day count (e.g. --fail-if-expiring 12345). In the rare case an
org's alias is purely numeric, pass the org first (check_expiration.sh 12345 --fail-if-expiring 7) so it isn't mistaken for the threshold.
If an org isn't authenticated (no saved credentials, or an expired/revoked token), the script does not fail silently — it prints the exact command to log in and then re-run:
my-trial not authenticated — no saved credentials for this org
To authenticate, run one of:
sf org login web --alias "my-trial"
sf org login web --alias <my-alias> --instance-url https://test.salesforce.com
Then re-run this check. List existing logins with: sf org list
sf org login web opens a browser to complete the OAuth flow. Use
--instance-url https://test.salesforce.com for sandboxes, or a custom My
Domain URL where applicable.
# Trial/DE expiration for one org (null = not a trial / paid org):
sf data query --query "SELECT Id, TrialExpirationDate FROM Organization" --target-org <org> --json
# Scratch org expiration comes from the org list, not SOQL:
sf org list --json
sf) and jq on the PATH, plus at least one
authenticated org (sf org login web).sf commands concurrently — the CLI can be slow under
contention. The script queries orgs sequentially for this reason.sf org list exposes a trailExpirationDate (note the typo) field that is
often null; the script does not rely on it for trial/DE orgs — it uses the
SOQL TrialExpirationDate, which is reliable. It does use expirationDate
from the list for scratch orgs.