Add temporal schedule list-matching-times command …

[NasitSony]

Implements the ListScheduleMatchingTimes RPC in the CLI.
Allows users to preview when a schedule will fire within
a given time range without executing workflows.

What was changed

Added temporal schedule list-matching-times command implementing the ListScheduleMatchingTimes RPC. Added functional tests for both text and JSON output. Fixed JSON output to use PrintStructured for proper array format.

Why?

The Temporal CLI was missing a command for the ListScheduleMatchingTimes RPC. Users can now preview when a schedule would fire within a given time range without executing workflows.

Checklist

1. Closes feat: add schedule list-matching-times command #1030
2. How was this tested: Functional tests added for text and JSON output. Full test suite passes (go test ./...).
3. Any docs updates needed? No — command description is auto-generated from YAML.

[CLAassistant]

All committers have signed the CLA.

[chaptersix]

@NasitSony thank you for your contribution! Could to add a functional test for this command? 1 with the human readable output and 1 with json?

Also, there's a new PR template, could you follow it?

[NasitSony]

@chaptersix Thanks for the feedback! I'll add the functional tests and update to the new PR template.

[NasitSony]

@chaptersix Added functional tests for text and JSON output, and fixed JSON output to use PrintStructured for proper array format. Also updated the PR description to follow the new template. Ready for review.

[chaptersix]

Related issues

Closes #1030

What changed?

Adds temporal schedule list-matching-times command implementing the ListScheduleMatchingTimes RPC. Allows users to preview when a schedule's spec would match within a given time range (past or future) without taking any actions.

Checklist

Stability

• Breaking changes are marked with 💥 in the PR title and release notes
• Changes to JSON output (-o json / -o jsonl) are treated as breaking changes

Design

• This feature does not depend on Cloud-only APIs or behavior (it works against an OSS server)
• New commands follow temporal <noun> <verb> structure (e.g. temporal workflow start)
• New flags are named after the API concept, not the implementation mechanism (good: --search-attribute, bad: --index-field)
• New flags don't duplicate an existing flag that serves the same purpose
• New flags do not have short aliases without strong justification
• Experimental features are marked with (Experimental feature) in commands.yaml

Help text (see style guide at the top of commands.yaml)

• All flags shown in help text and examples are implemented and functional
• Summaries use sentence case and have no trailing period
• Long descriptions end with a period and include at least one example invocation
• Examples use long flags (--namespace, not -n), one flag per line
• Placeholder values use YourXxx form (YourWorkflowId, YourNamespace)

Behavior

• Results go to stdout; errors and warnings go to stderr
• Error messages are lowercase with no trailing punctuation

Tests

• Added functional test(s) (SharedServerSuite)
• Added unit test(s) (func TestXxx) where applicable

Manual tests

Setup

temporal server start-dev --headless
temporal schedule create \
    --schedule-id YourScheduleId \
    --interval 1h \
    --workflow-id YourWorkflowId \
    --task-queue YourTaskQueue \
    --workflow-type YourWorkflowType

Happy path

$ temporal schedule list-matching-times \
    --schedule-id YourScheduleId \
    --start-time 2025-01-01T00:00:00Z \
    --end-time 2025-01-01T23:59:59Z
  Time
  2025-01-01T00:00:00Z
  2025-01-01T01:00:00Z
  ...

$ temporal schedule list-matching-times \
    --schedule-id YourScheduleId \
    --start-time 2025-01-01T00:00:00Z \
    --end-time 2025-01-01T23:59:59Z \
    -o json
{"startTime":["2025-01-01T00:00:00Z","2025-01-01T01:00:00Z",...]}

Error case

$ temporal schedule list-matching-times \
    --schedule-id nonexistent-id \
    --start-time 2025-01-01T00:00:00Z \
    --end-time 2025-01-01T23:59:59Z
Error: ...
$ echo $?
1

Composition

$ temporal schedule list-matching-times \
    --schedule-id YourScheduleId \
    --start-time 2025-06-01T00:00:00Z \
    --end-time 2025-06-07T23:59:59Z \
    -o json | jq '.startTime | length'
168

[chaptersix]

@NasitSony, I went ahead and made some corrections while I have time to review. Thanks again!