fix(cli): clarify --tz help text for offset-less --at values by rrrrrredy · Pull Request #69975 · openclaw/openclaw

rrrrrredy · 2026-04-22T04:12:19Z

Summary

clarify the --tz help text in cron add and cron edit to say it applies to both --cron expressions and offset-less --at values
align cron edit --at help text with cron add so the --tz behavior is discoverable from both commands

Why

The previous --tz wording implied it only affected cron expressions. In practice, it also affects offset-less --at values such as 09:00, so the old help text was incomplete and easy to misread.

This PR is a clean replacement for #59487 with only the intended CLI help-text scope.

User Impact

Users reading openclaw cron add --help or openclaw cron edit --help get a more accurate explanation of when --tz applies, including the Gateway-host local timezone default.

Root Cause

The CLI help text drifted from the actual behavior: runtime scheduling already uses --tz for offset-less --at values, but the exposed help text still described it as cron-only.

Validation

git diff --check
node scripts/run-vitest.mjs src/cli/cron-cli.test.ts (92 tests)
local Codex autoreview after maintainer repair: clean, no actionable findings

Real behavior proof

Behavior or issue addressed: The repaired help text documents that offset-less cron add --at and cron edit --at values use --tz, while cron expressions still default to the Gateway host local timezone.
Real environment tested: Repaired OpenClaw source checkout at a9bfdc2884e67c7032189767a5a5d8372ef2a792, Node v26.0.0, with repository dependencies available from the local full checkout.
Exact steps or command run after this patch: Emitted the actual registered Commander help for cron add and cron edit from the repaired source CLI registration with node --import tsx.

Evidence after fix: Terminal output from the repaired source help probe:

$ node --import tsx <source-help-probe> cron add --help
  --at <when>                      Run once at time (ISO with offset, or
                                   +duration). Use --tz for offset-less
  --tz <iana>                      Timezone for cron expressions (IANA; cron
                                   default: Gateway host local timezone)

$ node --import tsx <source-help-probe> cron edit --help
  --at <when>                          Set one-shot time (ISO, offset-less uses
                                       --tz) or duration like 20m
  --tz <iana>                          Timezone for cron expressions (IANA; cron
                                       default: Gateway host local timezone)

Observed result after fix: The copied live output shows cron add --at tells users to use --tz for offset-less datetimes, cron edit --at now says offset-less values use --tz, and both --tz help entries preserve the Gateway-host local timezone default.
What was not tested: No known gaps for this help-text-only change; full packaged CLI startup was not used because this local shell lacks global pnpm, so the proof used the repaired source command registration directly.

Remove incorrect UTC default from --tz help text

The new help text says --tz defaults to UTC for interpreting both --cron and offset-less --at, but cron expressions without tz are actually evaluated in the host timezone (see resolveCronTimezone in src/cron/schedule.ts, which falls back to Intl.DateTimeFormat().resolvedOptions().timeZone). This can mislead users into omitting --tz and getting local-time cron execution instead of UTC, so the wording should not claim a UTC default for --cron behavior.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c3816be7c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-22T05:22:59Z

-      .option("--tz <iana>", "Timezone for cron expressions (IANA)")
+      .option(
+        "--tz <iana>",
+        "Timezone for interpreting --cron expressions and offset-less --at datetime strings (IANA, default: UTC)",


Remove UTC default claim from cron edit --tz help

This help text now states that --tz defaults to UTC, but cron schedules without tz are evaluated in the host timezone (resolveCronTimezone in src/cron/schedule.ts falls back to Intl.DateTimeFormat().resolvedOptions().timeZone). In cron edit, that mismatch can cause users to omit --tz while changing --cron and get local-time execution instead of UTC, so the wording should avoid claiming a UTC default for cron behavior.

Useful? React with 👍 / 👎.

rrrrrredy · 2026-04-23T01:46:17Z

Status update as of 2026-04-23: this is the active clean respin for #59456, the issue/PR links are now corrected, and the current checks are green. If the help-text-only scope looks right, I would appreciate maintainer review on this version.

prtags · 2026-04-23T18:43:51Z

Related work from PRtags group tidy-squirrel-pxzl

Title: Open PR duplicate: cron --tz help text clarification for offset-less --at

Number	Title
#59480	fix: clarify --tz help text to mention --at support (#59456)
#59487	fix(cli): clarify --tz help text to cover --at time-only format
#69975*	fix(cli): clarify --tz help text for offset-less --at values

* This PR

clawsweeper · 2026-04-29T04:25:53Z

Codex review: needs real behavior proof before merge.

Latest ClawSweeper review: 2026-05-20 09:39 UTC / May 20, 2026, 5:39 AM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The PR changes cron CLI help text for --tz and cron edit --at so timezone handling is discoverable for offset-less --at values.

Reproducibility: yes. Source inspection shows the PR adds a combined default: UTC claim while current main's runtime, help text, and tests preserve the Gateway-host timezone default for recurring cron schedules.

PR rating
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦪 silver shellfish
Summary: The PR is small and useful in intent, but missing real behavior proof plus incorrect default wording make it not quality-ready.

Rank-up moves:

Remove or split the UTC-default claim so recurring cron keeps the host-local default wording.
Refresh the branch against current main without losing the narrow cron edit --at discoverability improvement.
Add redacted rendered output for openclaw cron add --help and openclaw cron edit --help.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Needs real behavior proof before merge: The PR body says the rendered help commands were not run and includes no after-fix output; add redacted terminal output or screenshots and update the PR body for re-review.

Risk before merge

Merging as-is would tell users that combined --cron and offset-less --at timezone interpretation defaults to UTC, while recurring cron schedules without tz use the Gateway host local timezone.
GitHub reports the PR branch as conflicting with current main, so the final help text needs a careful refresh against the host-local wording added after this branch was opened.
The contributor has not provided rendered cron add --help and cron edit --help output after the patch.

Maintainer options:

Decide the mitigation before merge
Refresh the branch so cron edit --at and, if needed, --tz help mention offset-less one-shot datetime handling without changing the documented host-local default for recurring cron schedules.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge
Contributor action is required for proof, conflict refresh, and wording correction; ClawSweeper should not take over while the external proof gate is missing.

Security
Cleared: The diff only changes two CLI help strings and does not alter execution, dependencies, secrets, CI, package metadata, or supply-chain surfaces.

Review findings

[P2] Remove the UTC default from cron add help — src/cli/cron-cli/register.cron-add.ts:89
[P2] Remove the UTC default from cron edit help — src/cli/cron-cli/register.cron-edit.ts:59

Review details

Best possible solution:

Refresh the branch so cron edit --at and, if needed, --tz help mention offset-less one-shot datetime handling without changing the documented host-local default for recurring cron schedules.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection shows the PR adds a combined default: UTC claim while current main's runtime, help text, and tests preserve the Gateway-host timezone default for recurring cron schedules.

Is this the best way to solve the issue?

No, not as written. The narrow help-text direction is good, but recurring cron defaults and offset-less one-shot --at defaults need separate wording.

Label justifications:

P2: This is a focused CLI help correction with limited blast radius, but the current wording would mislead users about cron timezone defaults.
rating: 🧂 unranked krab: Current PR rating is 🧂 unranked krab because proof is 🧂 unranked krab, patch quality is 🦪 silver shellfish, and The PR is small and useful in intent, but missing real behavior proof plus incorrect default wording make it not quality-ready.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body says the rendered help commands were not run and includes no after-fix output; add redacted terminal output or screenshots and update the PR body for re-review.

Full review comments:

[P2] Remove the UTC default from cron add help — src/cli/cron-cli/register.cron-add.ts:89
The new --tz help says the default is UTC while describing both --cron and offset-less --at, but recurring cron schedules without tz use the Gateway host local timezone. Users could omit --tz expecting UTC cron execution and get local-time scheduling instead.
Confidence: 0.94
[P2] Remove the UTC default from cron edit help — src/cli/cron-cli/register.cron-edit.ts:59
cron edit --tz gets the same incorrect UTC default claim. Editing a job with --cron and no --tz still uses the host-local cron fallback, so this documents the wrong behavior for recurring schedules.
Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.94

What I checked:

PR diff adds UTC default to cron add help: The live PR changes cron add --tz to one combined description for --cron and offset-less --at with (IANA, default: UTC). (src/cli/cron-cli/register.cron-add.ts:89, 3c3816be7c6d)
PR diff repeats UTC default in cron edit help: The live PR applies the same combined UTC-default wording to cron edit --tz and separately changes cron edit --at to mention offset-less --tz handling. (src/cli/cron-cli/register.cron-edit.ts:59, 3c3816be7c6d)
Current main documents host-local cron default: Current main says cron add --tz is for cron expressions and that the cron default is the Gateway host local timezone; cron add --at already mentions using --tz for offset-less datetimes. (src/cli/cron-cli/register.cron-add.ts:98, 110042d840bb)
Current main still has a narrow edit help gap: Current main keeps cron edit --tz on the host-local cron wording, while cron edit --at still only says ISO or duration, so the useful remaining change is narrower than the PR's combined default text. (src/cli/cron-cli/register.cron-edit.ts:81, 110042d840bb)
Runtime cron default is host-local: resolveCronTimezone returns the supplied tz when present and otherwise falls back to Intl.DateTimeFormat().resolvedOptions().timeZone, not UTC. (src/cron/schedule.ts:14, 110042d840bb)
Tests lock the host-local help contract: The cron CLI test asserts that both cron add and cron edit help include Gateway host local timezone, directly contradicting the PR's combined UTC-default wording. (src/cli/cron-cli.test.ts:283, 110042d840bb)

Likely related people:

chen-zhang-cs-code: Authored the merged cron local-time guidance change that added the current host-local --tz help wording and regression test. (role: recent cron timezone help contributor; confidence: high; commits: 5741e40c1414; files: src/cli/cron-cli/register.cron-add.ts, src/cli/cron-cli/register.cron-edit.ts, src/cli/cron-cli.test.ts)
steipete: Landed the one-shot --at --tz parser/docs/test behavior that this help text is trying to describe. (role: recent adjacent cron parser contributor; confidence: high; commits: 0cbf6d5fed5b; files: src/cli/cron-cli/shared.ts, src/cli/cron-cli/register.cron-edit.ts, docs/cli/cron.md)
RolfHegr: Credited on the merged change that first made --tz work with offset-less one-shot --at values in the cron CLI path. (role: introduced adjacent behavior; confidence: medium; commits: e7870c25e5ec; files: src/cli/cron-cli/shared.ts, src/cli/cron-cli/register.cron-add.ts, src/cli/cron-cli/register.cron-edit.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 110042d840bb.

clawsweeper · 2026-05-20T05:44:56Z

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

Where did the egg go?

The egg game starts only after the PR passes the real-behavior proof check.
Before that, no creature or rarity is rolled. The treat waits for real proof.
This is still just collectible flavor: proof affects review readiness, not creature quality.

rrrrrredy mentioned this pull request Apr 22, 2026

fix(cli): clarify --tz help text to cover --at time-only format #59487

Closed

21 tasks

openclaw-barnacle Bot added cli CLI command changes size: XS labels Apr 22, 2026

rrrrrredy marked this pull request as ready for review April 22, 2026 04:31

chatgpt-codex-connector Bot reviewed Apr 22, 2026

View reviewed changes

rrrrrredy force-pushed the codex/pr59487-clean branch 2 times, most recently from af0be1d to 3c3816b Compare April 22, 2026 05:20

chatgpt-codex-connector Bot reviewed Apr 22, 2026

View reviewed changes

rrrrrredy changed the title ~~[codex] fix(cli): clarify --tz help text for offset-less --at values~~ fix(cli): clarify --tz help text for offset-less --at values Apr 22, 2026

rrrrrredy mentioned this pull request Apr 23, 2026

[Docs/UX]: help text is misleading — says "cron expressions" only, but should also apply to datetime strings #59456

Closed

rrrrrredy mentioned this pull request Apr 23, 2026

[Bug]: cron add --at does not support HH:MM time-only strings; --tz has no effect on --at #59441

Closed

prtags Bot mentioned this pull request Apr 23, 2026

fix: clarify --tz help text to mention --at support (#59456) #59480

Closed

2 tasks

clawsweeper Bot mentioned this pull request May 1, 2026

fix(cron): support HH:MM time-only strings in --at; apply --tz to time-only input #70046

Closed

openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 20, 2026

fix(cli): clarify --tz help text for offset-less --at values

a9bfdc2

vincentkoc force-pushed the codex/pr59487-clean branch from 3c3816b to a9bfdc2 Compare June 14, 2026 04:27

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 14, 2026

vincentkoc merged commit 231b5a1 into openclaw:main Jun 14, 2026
180 of 184 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(cli): clarify --tz help text for offset-less --at values#69975

fix(cli): clarify --tz help text for offset-less --at values#69975
vincentkoc merged 1 commit into
openclaw:mainfrom
rrrrrredy:codex/pr59487-clean

rrrrrredy commented Apr 22, 2026 •

edited by vincentkoc

Loading

Uh oh!

greptile-apps Bot commented Apr 22, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 22, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 22, 2026

Uh oh!

rrrrrredy commented Apr 23, 2026

Uh oh!

prtags Bot commented Apr 23, 2026

Uh oh!

clawsweeper Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

rrrrrredy commented Apr 22, 2026 • edited by vincentkoc Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

User Impact

Root Cause

Validation

Real behavior proof

Related

Uh oh!

greptile-apps Bot commented Apr 22, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

rrrrrredy commented Apr 23, 2026

Uh oh!

prtags Bot commented Apr 23, 2026

Uh oh!

clawsweeper Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rrrrrredy commented Apr 22, 2026 •

edited by vincentkoc

Loading

clawsweeper Bot commented Apr 29, 2026 •

edited

Loading