[autoscaler] Clarify head node commands in ray up output

[cyhapun]

Summary

This PR clarifies the CLI output shown during ray up.

Currently, ray up streams the output of ray start --head from the head node back to the user's local terminal. The ray start --head output includes "Next steps" commands that may only work from the head node or from within the cluster network, which can be confusing when viewed from the local machine running ray up.

This change updates the output text to make the execution context clearer:

• The ray start --head "Next steps" commands are identified as head-node / cluster-network commands.
• The ray up "Useful Commands" section is clarified as commands intended for the local machine.
• The head-node context note is only printed when ray start output is actually emitted, so it is not shown in --no-restart flows where ray start is skipped.
• Shared CLI output helper functions were added so the wording can be reused consistently and tested without requiring a full Ray native build.

fixes #40833

Testing

• ruff check passed.
• pytest python/ray/tests/test_cli_output_context.py passed: 11/11.
• Tests validate emitted CLI output behavior by calling the output helpers with mocked cli_logger / cf objects.
• Added coverage for the --no-restart gating behavior so the head-node context note is not emitted when ray_start_commands is empty.
• Reviewed git diff after the review updates.

Not run:

• Manual ray up <cluster_config.yaml> validation, because this environment does not have live cloud provider credentials.
• Direct ray start --head validation, because this environment does not have a fully built Ray installation with the _raylet native module.

Risk

Low risk: this is a CLI output text/formatting change only. The only control-flow change gates the informational context note so it is printed only when corresponding ray start output exists; it does not modify cluster launch logic.

[gemini-code-assist]

Code Review

This pull request clarifies the context of CLI commands in Ray by adding warnings and notes to distinguish between head node and local machine operations. It also introduces a test suite that validates these changes by inspecting source code strings. Feedback suggests using standard ASCII characters for separators and dimmed text instead of warnings for consistency across the CLI. Additionally, the testing approach was noted as fragile, with a recommendation to use more robust methods like mocking the logger to avoid maintenance burdens caused by minor source code changes.

[gemini-code-assist]

The use of the box-drawing character ─ (U+2500) is inconsistent with other separators in the codebase (e.g., python/ray/scripts/scripts.py:1087), which use the standard ASCII hyphen -. Using standard ASCII ensures better compatibility across various terminal emulators and maintains consistency with existing Ray CLI output.

Suggested change

	cf.dimmed("─" * 60)
	cf.dimmed("-" * 60)

[cyhapun]

Updated to use ASCII "-" separators for consistency with existing Ray CLI output.

[gemini-code-assist]

The use of cli_logger.warning for this contextual note is inconsistent with the implementation in python/ray/scripts/scripts.py (line 1092), which uses a dimmed print. A warning typically implies a potential error or an action required by the user, whereas this is an informational note about the execution context. Additionally, warning adds a [WARN] prefix in non-TTY environments, which might be misleading here. Consider using cli_logger.print(cf.dimmed(...)) for consistency with the head-node side of the output.

[cyhapun]

Changed this from cli_logger.warning to cli_logger.print(cf.dimmed(...)) since this is an informational context note, not a warning condition.

[gemini-code-assist]

Testing CLI output by performing string searches on the source code is highly fragile and creates a maintenance burden. These tests are tightly coupled to implementation details such as variable names, formatting, and specific line contents (e.g., lines 83-87). Any refactoring or minor wording changes in the source will break these tests even if the functional output remains correct. While the desire to avoid native builds is understood, consider using a more robust approach, such as mocking the cli_logger to verify its calls, or at least using regex patterns that are less sensitive to the exact source code structure.

[cyhapun]

Updated the tests to avoid source-code inspection. The output text is now produced by standalone helper functions, and the tests import those helpers directly with mocked cli_logger/cf objects to assert on emitted output behavior.

[TruongQuangPhat]

Hi Ray maintainers,

It looks like buildkite/microcheck failed in tests that seem unrelated to this PR's changed files, such as:

• //python/ray/tests:test_tempdir
• python/ray/tests/test_tempdir.py::test_worker_temp_dir_different_from_head
• //python/ray/tests:test_task_events

From the log, the failure appears to involve cleanup/runtime behavior, e.g. OSError: [Errno 39] Directory not empty: '/tmp/ray', while this PR only changes CLI output text/helpers and the related CLI output context tests.

Could you please advise whether this should be retried or if there is anything I should adjust on my side?

Thank you!

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 761a944. Configure here.}

[Hutaph]

Hi @edoakes, could you please review this PR when you have a chance?

I’ve addressed the latest CI issues:

• Fixed the earlier lint/pre-commit failures.
• Removed duplicate GCS actor manager tests that caused the core test failure.
• Fixed the latest test_cli_output_context and test_parquet_schema_inference microcheck failures.
• Microcheck is now green.

Thank you very much!

[edoakes]

@cyhapun could you please post some screenshots of full log output for relevant commands before & after the change?

[cyhapun]

@cyhapun could you please post some screenshots of full log output for relevant commands before & after the change?

Thanks for asking. I tried to capture live command output locally, but my current WSL environment does not have the ray CLI installed/built, and I also do not have cloud provider credentials available for a live ray up run.

To still make the output change reviewable, I’m including the before/after diffs from the CLI golden pattern files used by CI:

• test_ray_start.txt covers the expected ray start --head output.
• test_ray_up.txt covers the expected ray up output.

These pattern files are what the existing CLI tests match against, so they reflect the expected full CLI output changes covered by CI. Note that some characters are escaped because these files are regex patterns, not raw terminal output.

ray start --head before/after pattern diff

diff --git a/tmp-output/test_ray_start_before.txt b/tmp-output/test_ray_start_after.txt
index 6d6df437a1..84b5d2549d 100755
--- a/tmp-output/test_ray_start_before.txt
+++ b/tmp-output/test_ray_start_after.txt
@@ -6,6 +6,9 @@ Ray runtime started.
 --------------------
 
 Next steps
+  Note: The following commands are intended for use on
+  the head node or within the cluster network\.
+
   To add another node to this Ray cluster, run
     ray start --address='.+'

ray up before/after pattern diff

diff --git a/tmp-output/test_ray_up_before.txt b/tmp-output/test_ray_up_after.txt
index 0da266aaed..a8daf24dce 100755
--- a/tmp-output/test_ray_up_before.txt
+++ b/tmp-output/test_ray_up_after.txt
@@ -41,7 +41,12 @@ Acquiring an up-to-date head node
   \[7/7\] Starting the Ray runtime
   New status: up-to-date
 
-Useful commands:
+-{60}
+Note: The output above is from the head node \(via `ray start`\)\.
+  Commands shown in 'Next steps' may only work from the head node
+  or from within the cluster network\.
+
+Useful commands for your local machine:
   To terminate the cluster:
     ray down .+

The main behavioral changes shown above are:

• ray start --head now labels the Next steps commands as intended for the head node or cluster network.
• ray up now separates the streamed head-node output from the local-machine commands.
• The ray up useful commands heading now explicitly says Useful commands for your local machine:.

I also attached a screenshot of the generated before/after pattern diff output from my local environment.

[edoakes]

CLI changes LGTM but I think there are some accidental inclusions here

[edoakes]

Hm this looks irrelevant -- was there a bad merge?

[edoakes]

same here -- bad merge?

[Hutaph]

@edoakes Thank you for pointing this out, and I apologize for the confusion. These unrelated files were added by mistake when @TruongQuangPhat resolved merge conflicts. I have removed them from the PR. The remaining changes are only for the CLI output update.