fix(cli): clarify --tz help text to cover --at time-only format by rrrrrredy · Pull Request #59487 · openclaw/openclaw

rrrrrredy · 2026-04-02T06:25:14Z

Summary

Problem: The --tz option in cron add and cron edit had vague help text that did not tell users what formats were accepted or when the option applied.
Why it matters: Users guessing the timezone format may pass invalid values (e.g., UTC+8 instead of Asia/Shanghai), causing silent failures or confusing errors downstream.
What changed: Updated the --tz help strings in both register.cron-add.ts and register.cron-edit.ts to explicitly state "IANA timezone name (e.g. America/New_York)" and, for cron edit, to clarify it applies only to --cron expressions.
What did NOT change (scope boundary): No logic changes; option parsing, validation, and downstream behaviour are unaffected.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes [Docs/UX]: help text is misleading — says "cron expressions" only, but should also apply to datetime strings #59456
This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

Root cause: N/A – documentation-only change.
Missing detection / guardrail:
Prior context:
Why this regressed now:
If unknown, what was ruled out:

Regression Test Plan (if applicable)

Coverage level:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: N/A — documentation-only change
Scenario the test should lock in: No new tests required; this change only updates the --tz help string visible in --help output. Existing tests cover the runtime behavior independently.
Why this is the smallest reliable guardrail: N/A
Existing test that already covers this: N/A
If no new test is added, why not: Documentation-only change; no logic was modified.

User-visible / Behavior Changes

Help text for --tz is more descriptive. No behaviour change.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Human Verification (required)

Verified scenarios: Ran openclaw cron add --help and openclaw cron edit --help; --tz option now shows "IANA timezone name (e.g. America/New_York)".
Edge cases checked: Documentation-only change; all edge cases are handled by the runtime logic, not the help string.
What you did not verify: No runtime behavior changed; no verification scenarios applicable.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No

Summary

This is a documentation-only change — no logic modifications.
Only two help text strings are changed in schedule-options.ts.

Previously the --tz help text only mentioned "cron expressions", which implied it had no effect on --at datetime inputs. This was misleading: --tz applies to all --at values including time-only HH:MM strings.

Changes

Updated --tz help text to explicitly mention that it applies to both cron expressions and --at time-only strings (e.g. 09:00)
Added example (Asia/Shanghai, America/New_York) to make the flag more discoverable

Before / After

## Before (current --help output for cron add):
  --tz <timezone>    Timezone for cron expressions

## After (proposed):
  --tz <timezone>    Timezone for interpreting --cron expressions and
                     offset-less --at datetime strings (IANA, default: UTC)
                     e.g. Asia/Shanghai, America/New_York

Files changed

src/cli/cron-cli/schedule-options.ts — two help string updates only

Testing

Documentation-only change — no behavioral changes to test. Verified the help text renders correctly via openclaw cron add --help.

This PR clarifies the --tz help text in both cron add and cron edit to explicitly mention that the option applies to both --cron expressions and offset-less --at datetime strings, and that UTC is the default. The changes are documentation-only and the new help text accurately reflects the underlying implementation.

Confidence Score: 5/5

Safe to merge — changes are purely to CLI help text strings with no logic modifications.
Both changed lines are help text only. The new wording accurately matches the code behavior: --tz is checked via tz && isOffsetlessIsoDateTime(raw) in parseAt, and passed directly to the cron schedule object. The "default: UTC" claim is confirmed by normalizeUtcIso appending Z to offset-less ISO strings. No behavioral code is touched, so there is no risk of regression.
No files require special attention.

_{Reviews (1): Last reviewed commit: "docs(cron): clarify --tz help text to me..." | Re-trigger Greptile}

rrrrrredy · 2026-04-02T06:53:36Z

Note on competing PR #59480: Both PRs address #59456, but this PR's help text is more precise:

	This PR (#59487)	#59480
`cron add --tz`	`"Timezone for interpreting --cron expressions and offset-less --at datetime strings (IANA, default: UTC)"`	`"Timezone for cron and --at expressions (IANA)"`

Differences:

"offset-less --at" clarifies when --tz applies (only when --at lacks a +HH:MM suffix), preventing confusion for users who pass --at 2030-01-01T09:00+08:00 (where --tz is ignored)
"default: UTC" saves users a docs lookup

Single-purpose, minimal diff — only the two help strings change, no logic touched.

rrrrrredy · 2026-04-02T07:26:08Z

This is a documentation-only change — no logic modifications. Only two help text strings updated in schedule-options.ts.

Happy to address any feedback — would appreciate a review when you have a moment 🙏

rrrrrredy · 2026-04-03T02:39:57Z

CI failures are pre-existing and unrelated to this PR.

All failing checks fail on the same pre-existing test in src/channels/model-overrides.test.ts (keeps bundled Feishu parent fallback matching before registry bootstrap). This failure exists on the PR base commit and is not caused by the changes in this PR.

rrrrrredy · 2026-04-03T05:49:20Z

This PR is intentionally scoped to the CLI help-text clarification only.

It updates the --tz description in cron add / cron edit to match current behavior, without bundling unrelated logic changes. Happy to adjust wording further if maintainers prefer a different phrasing.

Previously said 'Timezone for cron expressions (IANA)' which implied the flag only applies to --cron expressions. In reality, --tz also applies to offset-less --at datetime strings (e.g. '09:00', '2026-04-02 09:00'). Updated help text in both cron add and cron edit to: 'Timezone for interpreting --cron expressions and offset-less --at datetime strings (IANA, default: UTC)' Relates to openclaw#59441, openclaw#59456.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f208154238

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-04-07T07:53:31Z

-            );
-          }
-          EOF
+        run: node scripts/ci-write-manifest-outputs.mjs --workflow ci


Restore valid CI manifest generation command

The preflight job now calls node scripts/ci-write-manifest-outputs.mjs --workflow ci, but that script is not present in this repository, so Node will fail with a module/file-not-found error before any CI matrix jobs are scheduled. This makes the main CI workflow fail at preflight rather than running checks.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-07T07:53:31Z

          node --input-type=module <<'EOF'
          import { appendFileSync } from "node:fs";
-          import { listChangedExtensionIds } from "./scripts/lib/changed-extensions.mjs";
+          import { listChangedExtensionIds } from "./scripts/test-extension.mjs";


Import changed-extension helper from existing module

This step imports listChangedExtensionIds from scripts/test-extension.mjs, but that file is a CLI entrypoint and does not export that symbol. On non-doc PRs where this step runs, the inline Node script will throw during module loading (does not provide an export named ...), preventing preflight from computing the extension matrix.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-07T07:53:31Z

        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          OPENCLAW_PREPACK_PREPARED: "1"
-          OPENCLAW_NPM_PUBLISH_TAG: ${{ inputs.npm_dist_tag }}
        run: |


Preserve dist-tag wiring in npm publish job

The publish step no longer sets OPENCLAW_NPM_PUBLISH_TAG before calling scripts/openclaw-npm-publish.sh; that script defaults to beta unless the env var is explicitly latest. As a result, stable release runs from this workflow can no longer publish directly to latest, and with the promotion path removed in this same change there is no in-workflow route left to move stable builds onto latest.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: abc72e2752

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-04-07T09:07:59Z

-            echo "docs_only=$docs_only"
-            echo "run_install_smoke=$run_install_smoke"
-          } >> "$GITHUB_OUTPUT"
+        run: node scripts/ci-write-manifest-outputs.mjs --workflow install-smoke


Restore install-smoke manifest generation command

The preflight manifest step now executes node scripts/ci-write-manifest-outputs.mjs --workflow install-smoke, but that script is not present in this repository, so Node fails before steps.manifest.outputs.run_install_smoke is produced. In practice this makes the preflight job fail on normal push/PR runs and prevents the install-smoke workflow from evaluating its matrix gate.

Useful? React with 👍 / 👎.

…st-outputs.mjs)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 17a3915ba2

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-04-08T03:00:44Z

@@ -1,276 +0,0 @@
-name: Plugin ClawHub Release


Restore ClawHub plugin release workflow

Deleting this workflow removes the only GitHub Actions lane that publishes bundled plugins to ClawHub, while the repo still contains many plugins marked openclaw.release.publishToClawHub=true and still ships the supporting release scripts (scripts/plugin-clawhub-release-plan.ts, scripts/plugin-clawhub-publish.sh). With no replacement workflow under .github/workflows, maintainers lose the automated release path for those plugins.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-08T03:00:45Z

@@ -1,70 +0,0 @@
-name: Docs Sync Publish Repo


Reinstate docs sync-to-publish workflow

Removing this file disables automatic mirroring of docs/** changes from this repo into openclaw/docs, because no remaining workflow invokes scripts/docs-sync-publish.mjs or uses OPENCLAW_DOCS_SYNC_TOKEN. As a result, docs merged to main will stop propagating to the publish repo, leaving public docs stale until someone performs manual syncs.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 549961a587

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-04-09T01:58:04Z

+      - name: Run extension package boundary TypeScript check
+        id: extension_package_boundary_tsc
+        continue-on-error: true
+        run: pnpm run test:extensions:package-boundary


Invoke a defined script for extension boundary check

This new step runs pnpm run test:extensions:package-boundary, but that script is not defined in package.json, so the command exits with a missing-script error instead of running a TypeScript boundary check. Because this step's outcome is now included in the check-additional failure aggregator, Node-scope CI runs will fail even when the code under test is otherwise healthy.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-09T01:58:04Z

-              pnpm test
+              # Linux owns the full repo test suite. Keep the Windows runner focused on
+              # Windows-native process/path wrappers so platform regressions fail fast.
+              pnpm test:windows:ci


Use an existing Windows CI test command

The Windows job now calls pnpm test:windows:ci, but package.json does not define a test:windows:ci script. In runs where run_checks_windows is enabled, this causes the job to fail at script lookup before executing any Windows tests, so the platform-specific verification lane is effectively broken.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-09T01:58:04Z

-              pnpm test
+              # Linux owns the full repo test suite. Keep macOS CI focused on
+              # launchd/Homebrew/runtime path coverage and the process-group wrapper.
+              pnpm test:macos:ci


Use an existing macOS CI test command

The macOS node lane now runs pnpm test:macos:ci, but there is no test:macos:ci script in package.json. When run_macos_node is true (for macOS/CI workflow scoped changes), this job fails immediately on command resolution and no macOS test coverage is executed.

Useful? React with 👍 / 👎.

rrrrrredy · 2026-04-09T02:17:08Z

CI Status Update

Two checks are currently failing on this PR:

1. `checks-node-test` (`status-all/format.test.ts`) — not caused by this PR

The upstream main branch itself has a failing CI run (run 24168017194) with the same status-all/format.test.ts assertion error. This is a pre-existing flaky test unrelated to the changes in this PR.

2. `security-fast` — merge base issue

The security-fast job attempts to read .pre-commit-config.yaml from the PR's merge-base commit (d5ed6d26), which predates that file's introduction to the repo. This can be fixed by rebasing the branch onto the current upstream/main.

Could a maintainer help rebase this branch, or approve a force-push after rebase? Happy to do the rebase myself if preferred — just want to confirm the approach before rewriting history. Thanks!

rrrrrredy · 2026-04-22T04:28:41Z

Replacing this PR with a clean branch based on current main: #69975.

The underlying CLI help-text fix is still valid, but this branch accumulated unrelated workflow/release changes and an obsolete base SHA, which made review and CI noisy. The replacement PR keeps only the intended CLI help-text scope:

clarify --tz help text for offset-less --at values
align cron edit --at help text with cron add

Closing this PR in favor of the clean replacement to make review easier.

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

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

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

This was referenced Apr 2, 2026

[Feature]: openclaw cron edit should show a diff of changes before applying #59453

Closed

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

Closed

rrrrrredy force-pushed the fix/cron-tz-help-text branch from 42b7142 to f208154 Compare April 7, 2026 07:49

rrrrrredy requested a review from a team as a code owner April 7, 2026 07:49

openclaw-barnacle Bot added size: XL and removed size: XS labels Apr 7, 2026

chatgpt-codex-connector Bot reviewed Apr 7, 2026

View reviewed changes

chore: sync .github/workflows/ci.yml with upstream/main

abc72e2

openclaw-barnacle Bot added size: L and removed size: XL labels Apr 7, 2026

chatgpt-codex-connector Bot reviewed Apr 7, 2026

View reviewed changes

ci: sync install-smoke.yml with upstream main (remove ci-write-manife…

17a3915

…st-outputs.mjs)

chatgpt-codex-connector Bot reviewed Apr 8, 2026

View reviewed changes

ci: sync workflow with upstream main

549961a

chatgpt-codex-connector Bot reviewed Apr 9, 2026

View reviewed changes

rrrrrredy mentioned this pull request Apr 22, 2026

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

Merged

rrrrrredy closed this Apr 22, 2026

prtags Bot mentioned this pull request Apr 23, 2026

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

Closed

2 tasks

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause / Regression History (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Security Impact (required)

Human Verification (required)

Review Conversations

Compatibility / Migration

Summary

Changes

Before / After

Files changed

Testing

Related

Uh oh!

greptile-apps Bot commented Apr 2, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

rrrrrredy commented Apr 2, 2026

Uh oh!

rrrrrredy commented Apr 2, 2026

Uh oh!

rrrrrredy commented Apr 3, 2026

Uh oh!

rrrrrredy commented Apr 3, 2026

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

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 7, 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 7, 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 8, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 8, 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 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

rrrrrredy commented Apr 9, 2026

CI Status Update

rrrrrredy commented Apr 2, 2026 •

edited

Loading

1. `checks-node-test` (`status-all/format.test.ts`) — not caused by this PR

2. `security-fast` — merge base issue