Repository navigation
Enter-PSSession - Clear-Host on non-Windows target fails #28118
Description
Prerequisites
- Write a descriptive title.
- Make sure you are able to repro it on the latest released version
- Search the existing issues.
- Refer to the FAQ.
- Refer to Differences between Windows PowerShell 5.1 and PowerShell.
Steps to reproduce
When connecting to a non-Windows target (Linux, macOS), the clear command resolves to the /usr/bin/clear command and Clear-Host is a thin wrapper around calling /usr/bin/clear and writing those values to the console.
${function:Clear-Host}
[Console]::Write((
& (Get-Command -CommandType Application clear | Select-Object -First 1).Definition
))
# .Link
# https://go.microsoft.com/fwlink/?LinkID=2096480
# .ExternalHelp System.Management.Automation.dll-help.xmlThis has two problems:
- SSH subsystems strip the
TERMenv var needed for/usr/bin/clearto work
- Direct console calls are a no-op due to the console stdout being used for PSRP messages
The only way to get this working is to explicitly set $env:TERM = '...' but this cannot be set generically as it must match up with the TERM you are using locally. You probably can just set it to xterm and it'll match your terminal locally but there's no guarantee that you actually use an xterm compatible terminal. In my case I do and setting it will work.
Screen.Recording.2026-09-29.at.4.42.52.am.mov
There is a slight side effect in that the console cursor is one line down due to the sequence of processing the new prompt after running a command but that is more cosmetic.
Running Clear-Host rather than clear fails because of the [Console]::Write(clear) doing to /dev/null even with $env:TERM explicitly set.
Screen.Recording.2026-09-29.at.4.46.21.am.mov
What I really think should be happening to fix this is for a remote PSSession on non-Windows to act more like how a Windows target works in that:
- It defines an alias for
clearto point toClear-Host - Has
Clear-Hostrun the following (like on Windows) - Both of these only apply when connecting to a PSRemoting endpoint, normal PowerShell sessions keep the existing clear/Clear-Host behaviour
# ${function:Clear-Host}
$RawUI = $Host.UI.RawUI
$RawUI.CursorPosition = @{X=0;Y=0}
$RawUI.SetBufferContents(
@{Top = -1; Bottom = -1; Right = -1; Left = -1},
@{Character = ' '; ForegroundColor = $rawui.ForegroundColor; BackgroundColor = $rawui.BackgroundColor})
# .Link
# https://go.microsoft.com/fwlink/?LinkID=2096480
# .ExternalHelp System.Management.Automation.dll-help.xmlThis means the clear operation goes to the actual PSRemoting host call method with known values and this is interpreted locally to call Console.Clear() or /usr/bin/clear if desired. The remote side continues to stay agnostic of the TERM setting and has the local client handle all that as it is better suited to managing the terminal which is actually local.
Please note this is different to #28115 which is specifically around connecting to a Windows target from a non-Windows client. This is about connecting to a non-Windows target from any client.
Expected behavior
The console is clearedActual behavior
`/usr/bin/clear` outputs `TERM environment not set.` and nothing is cleared.Error details
No error, the output is from `/usr/bin/term`Environment data
Not applicable, present on all PowerShell 7.x versions on non-Windows targetsVisuals
See steps to reproduce.
Activity
jborean93 commentedon Sep 28, 2026
I'm happy to send the PR for implementing the
Clear-Hostchanges when a remote PSSession is started but it would need the relevant working group's agreement before I spend time on it.iSazonov commentedon Sep 29, 2026
History #8609 #8603 #8554
In other words, do we need to correctly implement RawUI.SetBufferContents() ? Including older versions?
jborean93 commentedon Sep 29, 2026
Ilya (@iSazonov) I personally think that
clearandClear-Hoston local sessions should call[Console]::Clear()as internally it does the same thing as/usr/bin/clearbut this issue is specifically around howclear/Clear-Hostworks in a remote PSSession. As these remote sessions do not have an actual console set they should instead send some sort of trigger for the local PowerShell instance to callConsole.Clear()so the local process issues the clear VT sequences.My recommendation to solve this issue is for PowerShell to define
Clear-Hostand theclear -> Clear-Hostalias on remote session on all platforms. TheClear-Hostfunction would do the same as it does on Windows:This combined with the changes in #28116 would mean the local client treats this as a trigger to call
Console.Clear().The benefits of this approach:
clearstays the same for non-PSRemoting sessions so no change thereTERMis not set for/usr/bin/clearto work andClear-Hostrelies on[Console]::Write(...)to work which does not in remote PSSessionsI didn't submit a PR for this one though because it most likely will need a working group decision on the actual approach taken.
kilasuit commentedon Sep 29, 2026
From a quick glance I think this is fair enough. Will review a bit deeper later on
Should be quite quick to get back on this Jordan Borean (@jborean93) from the I-UX group as we are meeting this week.
kilasuit commentedon Sep 29, 2026
Sorry Jordan Borean (@jborean93) we were. We are now not meeting until the 14th Oct. So will be after then.