dx-org-trial-expiration-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Org Expiration Check

Org过期检查

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.

确定单个Org、默认Org或所有已认证Org的过期时间、剩余天数以及是否已过期。结果会按优先级排序（已过期和即将过期的Org优先），并附带一行摘要。该技能还可输出机器可读格式用于告警、打印高风险Org的备份命令，并说明如何续期即将过期的试用版或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

在用户提出以下请求时触发：

“我的试用Org何时过期？” / “它是否仍在活跃或已过期？”
“我的试用版还剩多少天？”
“我的哪些Org即将过期？” / “哪些Org会在30天内过期？”
“提醒我/为过期Org设置cron任务”（使用
```
--json
```
+
```
--fail-if-expiring
```
）。
“在我的Org过期前进行备份”（使用
```
--preserve
```
）。
“如何延长/续期我的试用版（或Developer Edition）Org？”（使用
```
--renew
```
）。

该技能支持试用版、Developer Edition Org（所有带有

TrialExpirationDate

的Org）以及scratch org（通过

sf org list

返回的

expirationDate

字段）。

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.

请勿在以下场景触发该技能：

沙箱刷新计时——这不属于过期日期范畴。
创建、删除或切换Org——该技能仅读取过期信息并提供指导；绝不会创建、删除、刷新或更改活跃/默认Org。（如需切换默认Org，请使用
```
dx-org-switch
```
。）
非Salesforce试用版——例如AWS免费套餐、Netflix或其他厂商的试用版。该技能仅适用于Salesforce。

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).

试用版/Developer Edition Org：权威来源是Org的
```
Organization.TrialExpirationDate
```
字段，通过SOQL（
```
sf data query
```
）读取。付费/生产Org的该字段为
```
null
```
，因此会显示无试用版过期日期——这是正常情况，而非错误。
scratch org：过期信息来自
```
sf org list
```
返回的
```
expirationDate
```
字段（无需对scratch org执行SOQL查询）。

Steps

操作步骤

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
```
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.
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.

关键步骤：运行附带的辅助脚本，该脚本可处理日期计算（剩余天数、已过期、即将过期警告）、优先级排序和结构化输出，适用于macOS和Linux系统。请始终通过技能目录的绝对路径调用该脚本——切勿使用
```
./scripts/
```
，因为该路径会基于用户当前目录解析，可能导致运行错误脚本或执行失败。
执行前请验证：
- ```
<skill_dir>
```
  是绝对路径（以
```
/
```
  开头），而非相对路径
- 该路径指向本技能所在目录（包含此SKILL.md的目录）
bash
```
bash "<skill_dir>/scripts/check_expiration.sh" <alias-or-username>   # 单个Org
bash "<skill_dir>/scripts/check_expiration.sh"                       # 默认Org（target-org配置）
bash "<skill_dir>/scripts/check_expiration.sh" --all                 # 所有已认证Org
bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30     # 仅检查30天内过期的Org
```
```
<skill_dir>
```
是包含此SKILL.md的目录的绝对路径。
将脚本输出反馈给用户。当某个Org无法查询时，显示脚本输出的
```
sf org login web
```
命令，方便用户进行认证。根据用户的需求选择可选参数（见下文）：用户想要保存工作时使用
```
--preserve
```
，用户询问如何延长时使用
```
--renew
```
，自动化场景使用
```
--json
```
/
```
--csv
```
，cron/CI网关场景使用
```
--fail-if-expiring
```
。

Options

可选参数

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

参数	用途
`--all` , `-a`	检查所有已认证Org。
`--within <days>` , `-w`	仅显示N天内过期的Org（包含已过期Org；排除付费/生产Org）。也可使用 `--within=30` 格式。
`--json`	输出Org记录的JSON数组（仅数据）。
`--csv`	输出CSV格式的行（仅数据）。
`--preserve`	打印即将过期/已过期Org的备份命令。
`--renew`	打印试用版/Developer Edition的延长与重新激活指南。
`--fail-if-expiring[=N]`	如果有Org在N天内过期，则以状态码3退出（默认N为7）。
`--no-scratch`	排除scratch org（仅检查试用版/Developer Edition）。
`--help` , `-h`	显示使用说明。

参数顺序灵活，且可组合使用（例如

--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:

text

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.

面向人类的输出按紧急程度分组——已过期Org优先，然后是即将过期（7天内，标记为

Warning

），接着是活跃Org，再是无试用版过期日期的Org，最后是无法查询的Org——输出末尾会附带一行摘要：

text

所有已认证Org的过期状态：

已过期：
  old-trial                       试用版/Developer Edition已于2026-06-20过期 （已过期19天）

即将过期（7天内）：
  almost-up                       试用版/Developer Edition将于2026-07-14过期 （剩余5天 警告）

活跃（非即将过期）：
  acme-trial                      试用版/Developer Edition将于2026-08-15过期 （剩余37天）
  my-scratch                      scratch org将于2026-07-25过期 （剩余16天）

无试用版过期日期（付费/生产）：
  prod                            无试用版过期日期（付费/生产Org）

摘要：1个已过期，1个将在7天内过期，2个活跃，1个无过期日期。

Structured output for alerting and cron (

--json

--csv

)

用于告警与cron任务的结构化输出（

--json

--csv

）

For dashboards, spreadsheets, or scheduled jobs, use

--json

--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.

bash

undefined

对于仪表板、电子表格或定时任务，可使用

--json

或

--csv

获取机器可读的记录（无描述性文本）。每条记录包含

org

、

kind

、

expirationDate

、

daysRemaining

（负数表示已过期，

null

表示无过期日期）、

status

和

orgId

。该输出是确定性的，无需LLM参与。

bash

undefined

JSON, filtered to orgs expiring within 30 days:

JSON格式，筛选30天内过期的Org：

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:

```bash

bash "<skill_dir>/scripts/check_expiration.sh" --all --within 30 --json


**Cron监控**——`--fail-if-expiring[=N]`在有Org在N天内过期时会以状态码3退出（并向stderr打印`ALERT:`行），因此定时任务可在Org过期前向您发送通知：

```bash

crontab: every morning at 9, alert if anything expires within 7 days

crontab：每天早上9点检查，如果有Org在7天内过期则发送告警

0 9 * * * bash "<skill_dir>/scripts/check_expiration.sh" --all --fail-if-expiring 7
|| mail -s "Salesforce org expiring soon" me@example.com

undefined

0 9 * * * bash "<skill_dir>/scripts/check_expiration.sh" --all --fail-if-expiring 7
|| mail -s "Salesforce Org即将过期" me@example.com

undefined

Preserve your work before an org lapses (

--preserve

)

在Org过期前保存工作（

--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

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

Org过期后，您将无法访问其元数据和数据。

--preserve

会为每个即将过期/已过期的Org打印可直接运行的备份命令（元数据清单+

retrieve

，以及批量数据导出）。该参数仅会打印命令——请您自行审核并执行：

bash

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

Extend or renew a trial / Developer Edition org (

--renew

)

延长或续期试用版/Developer Edition Org（

--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: request a Trial Org extension (up to +12 months) via
```
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.)
Nonprofits: email your Account Executive with subject "Trial Extension" and the trial-starter email, Org ID, and username; AMER
```
PowerOfUsDesk@salesforce.com
```
, other regions
```
myaccount@salesforce.com
```
/ 1-800-NO-SOFTWARE. Works even if already expired. (Article 004754220.)
Developer Edition: DE orgs have no subscription clock but are deactivated after prolonged inactivity (~180 days without a login); log in periodically. If locked (not yet deleted), open a Salesforce Customer Support case to reactivate — once permanently deleted, an org cannot be recovered.
To keep a standard trial's data/config, convert/subscribe to a paid edition before it lapses.

--renew

会打印保持Org活跃的当前指南，并显示高风险Org的Org ID，使操作更具可行性：

合作伙伴：通过
```
partners.salesforce.com
```
→ Ask Agentforce → "I want to extend my Trial Org"申请试用版Org延长（最长+12个月），需提供Org ID。仅适用于活跃或过期不足30天的Org；不适用于LDV Org。（Salesforce帮助文章编号000387818。）
非营利组织：发送邮件至您的客户经理，主题为"Trial Extension"，并附带试用版注册邮箱、Org ID和用户名；美洲地区发送至
```
PowerOfUsDesk@salesforce.com
```
，其他地区发送至
```
myaccount@salesforce.com
```
/ 1-800-NO-SOFTWARE。即使Org已过期也可申请。（帮助文章编号004754220。）
Developer Edition：Developer Edition Org无订阅期限，但长期未登录（约180天）会被停用；请定期登录。如果Org被锁定（尚未永久删除），可提交Salesforce客户支持工单重新激活——一旦永久删除，Org无法恢复。
如需保留标准试用版的数据/配置，请在过期前转换/订阅付费版本。

Exit codes

退出码

```
0
```
success
```
1
```
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 (

) takes precedence over an auth error (

): 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.

```
0
```
成功
```
1
```
某个Org无法查询（认证/连接错误）
```
2
```
使用方式错误或缺少依赖（
```
sf
```
或
```
jq
```
）
```
3
```
```
--fail-if-expiring
```
阈值被触发（至少有一个Org即将过期）

当两种情况同时存在时，

--fail-if-expiring

触发（状态码3）优先级高于认证错误（状态码1）：告警信号优先，确保监控任务仍能触发。如果您的任务还需检测无法访问的Org，请运行

--json

并检查记录中的

status: "auth_error"

，同时检查退出码。请注意，认证失败的Org无法进行日期检查，因此不会单独触发

--fail-if-expiring

。

未指定数字的

--fail-if-expiring

会将后续的纯数字参数视为天数（例如

--fail-if-expiring 12345

）。如果Org的别名是纯数字，请先传入Org（

check_expiration.sh 12345 --fail-if-expiring 7

），避免被误认为是阈值。

Authentication

认证

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:

text

  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.

如果某个Org未认证（无保存的凭据，或令牌已过期/被吊销），脚本不会静默失败——它会打印准确的登录命令，提示用户登录后重新运行：

text

  my-trial                       未认证——无此Org的保存凭据

  请运行以下命令之一进行认证：
    sf org login web --alias "my-trial"
    sf org login web --alias <my-alias> --instance-url https://test.salesforce.com
  然后重新运行检查。使用以下命令列出已登录的Org：  sf org list

sf org login web

会打开浏览器完成OAuth流程。沙箱环境请使用

--instance-url https://test.salesforce.com

，或适用的自定义My Domain URL。

Manual fallback (if the script is unavailable)

手动备选方案（当脚本不可用时）

bash

undefined

bash

undefined

Trial/DE expiration for one org (null = not a trial / paid org):

单个试用版/Developer Edition的过期日期（null表示非试用版/付费Org）：

sf data query --query "SELECT Id, TrialExpirationDate FROM Organization" --target-org <org> --json

Scratch org expiration comes from the org list, not SOQL:

scratch org的过期信息来自Org列表，而非SOQL：

sf org list --json

undefined

sf org list --json

undefined

Notes

注意事项

Requires the Salesforce CLI (
```
sf
```
) and
```
jq
```
on the PATH, plus at least one authenticated org (
```
sf org login web
```
).
Avoid launching many
```
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.

需要将Salesforce CLI（
```
sf
```
）和
```
jq
```
添加到PATH中，且至少有一个已认证的Org（通过
```
sf org login web
```
登录）。
避免同时运行多个
```
sf
```
命令——CLI在高并发下运行缓慢。因此脚本会按顺序查询Org。
```
sf org list
```
会暴露一个
```
trailExpirationDate
```
字段（注意拼写错误），该字段通常为
```
null
```
；脚本不会依赖该字段获取试用版/Developer Edition的过期信息——它会使用SOQL查询的
```
TrialExpirationDate
```
，该字段更可靠。脚本会使用Org列表中的
```
expirationDate
```
字段获取scratch org的过期信息。

dx-org-trial-expiration-check

Original

Translation

Org Expiration Check

Org过期检查

When to use

适用场景

When NOT to use

不适用场景

How expiration is determined

过期判定规则

Steps

操作步骤

Options

可选参数

Prioritized output

优先级输出

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

用于告警与cron任务的结构化输出（
`--json`
/
`--csv`
）

JSON, filtered to orgs expiring within 30 days:

JSON格式，筛选30天内过期的Org：

crontab: every morning at 9, alert if anything expires within 7 days

crontab：每天早上9点检查，如果有Org在7天内过期则发送告警

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

在Org过期前保存工作（
`--preserve`
）

Extend or renew a trial / Developer Edition org (
`--renew`
)

延长或续期试用版/Developer Edition Org（
`--renew`
）

Exit codes

退出码

Authentication

认证

Manual fallback (if the script is unavailable)

手动备选方案（当脚本不可用时）

Trial/DE expiration for one org (null = not a trial / paid org):

单个试用版/Developer Edition的过期日期（null表示非试用版/付费Org）：

Scratch org expiration comes from the org list, not SOQL:

scratch org的过期信息来自Org列表，而非SOQL：

Notes

注意事项

dx-org-trial-expiration-check

Original

Translation

Org Expiration Check

Org过期检查

When to use

适用场景

When NOT to use

不适用场景

How expiration is determined

过期判定规则

Steps

操作步骤

Options

可选参数

Prioritized output

优先级输出

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

用于告警与cron任务的结构化输出（--json / --csv）

JSON, filtered to orgs expiring within 30 days:

JSON格式，筛选30天内过期的Org：

crontab: every morning at 9, alert if anything expires within 7 days

crontab：每天早上9点检查，如果有Org在7天内过期则发送告警

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

在Org过期前保存工作（--preserve）

Extend or renew a trial / Developer Edition org (--renew)

延长或续期试用版/Developer Edition Org（--renew）

Exit codes

退出码

Authentication

认证

Manual fallback (if the script is unavailable)

手动备选方案（当脚本不可用时）

Trial/DE expiration for one org (null = not a trial / paid org):

单个试用版/Developer Edition的过期日期（null表示非试用版/付费Org）：

Scratch org expiration comes from the org list, not SOQL:

scratch org的过期信息来自Org列表，而非SOQL：

Notes

注意事项

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

用于告警与cron任务的结构化输出（
`--json`
/
`--csv`
）

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

在Org过期前保存工作（
`--preserve`
）

Extend or renew a trial / Developer Edition org (
`--renew`
)

延长或续期试用版/Developer Edition Org（
`--renew`
）