chore: add documentation to the coder ssh command regarding feature parity with ssh (#17827)

brettkolodny · matifali · web-flow · commit 73251cf5b2e5 · 2025-05-14T15:42:44.000-04:00
Closes [coder/internal#628](coder/internal#628) --------- Co-authored-by: M Atif Ali <atif@coder.com>
diff --git a/cli/ssh.go b/cli/ssh.go
@@ -92,6 +92,7 @@ func (r *RootCmd) ssh() *serpent.Command {
 		Annotations: workspaceCommand,
 		Use:         "ssh <workspace>",
 		Short:       "Start a shell into a workspace",
+		Long:        "This command does not have full parity with the standard SSH command. For users who need the full functionality of SSH, create an ssh configuration with `coder config-ssh`.",
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(1),
 			r.InitClient(client),
diff --git a/cli/testdata/coder_ssh_--help.golden b/cli/testdata/coder_ssh_--help.golden
@@ -5,6 +5,10 @@ USAGE:
 
   Start a shell into a workspace
 
+  This command does not have full parity with the standard SSH command. For
+  users who need the full functionality of SSH, create an ssh configuration with
+  `coder config-ssh`.
+
 OPTIONS:
       --disable-autostart bool, $CODER_SSH_DISABLE_AUTOSTART (default: false)
           Disable starting the workspace automatically when connecting via SSH.
diff --git a/docs/reference/cli/ssh.md b/docs/reference/cli/ssh.md
diff --git a/docs/user-guides/workspace-access/index.md b/docs/user-guides/workspace-access/index.md
@@ -33,6 +33,11 @@ coder ssh my-workspace
 
 Or, you can configure plain SSH on your client below.
 
+> [!Note]
+> The `coder ssh` command does not have full parity with the standard
+> SSH command. For users who need the full functionality of SSH, use the
+> configuration method below.
+
 ### Configure SSH
 
 Coder generates [SSH key pairs](../../admin/security/secrets.md#ssh-keys) for
