experimental/ssh: improve --help copy for ssh commands#5325
experimental/ssh: improve --help copy for ssh commands#5325TanishqDatabricks wants to merge 7 commits into
Conversation
Updates the help text for `databricks ssh`, `databricks ssh connect`, and `databricks ssh setup` based on the May 1 2026 Remote Development CUJ. - `databricks ssh`: common-workflows examples now lead with serverless (no flags), with the dedicated-cluster path as a follow-up. - `databricks ssh connect`: Long description groups example invocations by serverless vs dedicated. Unhides --name, --accelerator, --ide, --environment-version so users can discover them via --help. - `databricks ssh setup`: tightened Short/Long to clarify it's for dedicated clusters; users on serverless should just use connect. Co-authored-by: Isaac
…ands Co-authored-by: Isaac
Waiting for approvalBased on git history, these people are best suited to review:
Eligible reviewers: Suggestions based on git history. See OWNERS for ownership rules. |
anton-107
left a comment
anton-107
left a comment
There was a problem hiding this comment.
Thanks for cleaning up the help copy — direction is right. A few changes before merging:
1. Keep --environment-version hidden
This flag still isn't ready for users to discover via --help. Please restore cmd.Flags().MarkHidden("environment-version") in experimental/ssh/cmd/connect.go.
Unhiding --name, --accelerator, and --ide is fine.
2. Misaligned # comments in ssh.go workflow block
The first example uses two tabs before #, the other two use spaces. Actual rendered output of databricks ssh --help:
databricks ssh connect --ide=cursor # connect to serverless through Cursor
databricks ssh setup --name=<connection> --cluster=<cluster-id> # update ~/.ssh/config so you can reconnect to a dedicated cluster
ssh <connection> # connect to dedicated cluster after setup
The first # lands ~4 columns to the right of the other two (tab expands to the next 8-column tabstop). Replace the tabs with spaces so all three # align.
Same nit in connect.go: databricks ssh connect --accelerator=<GPU_type>\t# AI Runtime uses a tab. Renders fine in isolation but is inconsistent — spaces would be cleaner.
3. Inconsistent placeholder: <name> vs <connection>
ssh setup --help:`ssh <name>`ssh --helpworkflow:ssh <connection>and--name=<connection>
Pick one. <name> matches the flag name; <connection> reads as a concept but loses the link. Either is fine — just be consistent across both files.
Test plan
The PR's test plan checkbox is unchecked. Please run all three --help outputs and eyeball them before re-requesting review — that's what caught issue #2 here.
| databricks ssh connect --cluster=<cluster-id> --profile=<profile-name> # connect to a cluster without any setup | ||
| databricks ssh setup --name=my-compute --cluster=<cluster-id> # update local ssh config | ||
| ssh my-compute # connect to the compute using ssh client | ||
| databricks ssh connect --ide=cursor # connect to serverless through Cursor |
There was a problem hiding this comment.
The two tabs (\t\t) before # here expand to the next 8-column tabstop, which lands ~4 columns to the right of the # on the lines below (which use spaces). Replace the tabs with spaces so all three # columns line up.
| the SSH server and handling the connection proxy. | ||
| Connect to serverless: | ||
| databricks ssh connect | ||
| databricks ssh connect --accelerator=<GPU_type> # AI Runtime |
There was a problem hiding this comment.
Tab before # AI Runtime is inconsistent with the space-aligned comments used elsewhere in this help text. Use spaces here for consistency.
|
|
||
| This command configures SSH to connect to Databricks compute by adding | ||
| an SSH host configuration to your SSH config file. | ||
| After running setup, you can connect with ` + "`ssh <name>`" + `. |
There was a problem hiding this comment.
Placeholder is inconsistent across files: ssh.go uses <connection> (in both the workflow example and --name=<connection>), but here it's <name>. Pick one and use it consistently in both files — <name> keeps the link to the flag name, <connection> reads more conceptually.
Co-authored-by: Isaac
|
An authorized user can trigger integration tests manually by following the instructions below: Trigger: Inputs:
Checks will be approved automatically on success. |
2 participants
Summary
databricks ssh,databricks ssh connect, anddatabricks ssh setupto reflect current workflows (serverless-first, dedicated clusters as follow-up)--name,--accelerator,--ide, and--environment-versionflags onconnectso users can discover them via--helpsetupdescription to clarify it's for dedicated clusters onlyTest plan
databricks ssh --help,databricks ssh connect --help,databricks ssh setup --helpshow updated copyThis pull request and its description were written by Isaac.