{"id":16567520,"url":"https://github.com/jdhitsolutions/wttoolbox","last_synced_at":"2025-03-21T11:33:16.024Z","repository":{"id":43806431,"uuid":"261255931","full_name":"jdhitsolutions/WTToolbox","owner":"jdhitsolutions","description":":computer: A set of PowerShell commands for managing and using the Windows Terminal application.","archived":false,"fork":false,"pushed_at":"2022-05-25T13:43:06.000Z","size":4964,"stargazers_count":68,"open_issues_count":2,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-18T01:06:09.994Z","etag":null,"topics":["powershell","windowsterminal"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdhitsolutions.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-04T17:49:02.000Z","updated_at":"2025-03-13T09:45:11.000Z","dependencies_parsed_at":"2022-08-28T12:21:55.783Z","dependency_job_id":null,"html_url":"https://github.com/jdhitsolutions/WTToolbox","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdhitsolutions%2FWTToolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdhitsolutions%2FWTToolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdhitsolutions%2FWTToolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdhitsolutions%2FWTToolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdhitsolutions","download_url":"https://codeload.github.com/jdhitsolutions/WTToolbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244791883,"owners_count":20511020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["powershell","windowsterminal"],"created_at":"2024-10-11T21:06:47.346Z","updated_at":"2025-03-21T11:33:15.413Z","avatar_url":"https://github.com/jdhitsolutions.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WTToolBox\n\n[![PSGallery Version](https://img.shields.io/powershellgallery/v/WTToolbox.png?style=for-the-badge\u0026logo=powershell\u0026label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/WTToolBox/) [![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/WTToolBox.png?style=for-the-badge\u0026label=Downloads)](https://www.powershellgallery.com/packages/WTToolBox/)\n\n![WindowsTerminal](assets/wt-icon.png)\n\n## Windows Terminal Toolbox\n\nA set of PowerShell functions for managing and working with the [Windows Terminal](https://www.microsoft.com/store/productId/9N0DX20HK701) application from Microsoft. You can download the module from the PowerShell Gallery. This module should work on __Windows__ platforms under Windows PowerShell and PowerShell 7.\n\n```powershell\nInstall-Module WTToolBox [-scope CurrentUser]\n```\n\nOf course, it is assumed you have `Windows Terminal` installed, or you plan to install. If `Windows Terminal` is not installed, you will get a warning message when you import this module.\n\nIf you want some background information on Windows Terminal, take a look at [https://devblogs.microsoft.com/commandline/getting-started-with-windows-terminal/](https://devblogs.microsoft.com/commandline/getting-started-with-windows-terminal/).\n\n### __Important__\n\nWindows Terminal is intended for use on a Windows 10 or Windows 11 desktop. In fact, it is now the default on Windows 11. You __cannot__ install Windows Terminal on Windows Server 2016 or 2019. Those platform do not meet the Windows Terminal minimal requirements. Based on [issues](https://github.com/microsoft/terminal/issues?q=is%3Aissue+windows+server+2022) in the Windows Terminal Github repository, Windows Terminal should install on Windows Server 2022 but there still appear to be compatibility issue.\n\n## Module Commands\n\n* [Backup-WTSetting](docs/Backup-WTSetting.md)\n* [Export-WTProfile](docs/Export-WTProfile.md)\n* [Get-WTColorScheme](docs/Get-WTColorScheme.md)\n* [Get-WTCurrent](docs/Get-WTCurrent.md)\n* [Get-WTCurrentRelease](docs/Get-WTCurrentRelease.md)\n* [Get-WTKeyBinding](docs/Get-WTKeyBinding.md)\n* [Get-WTProcess](docs/Get-WTProcess.md)\n* [Get-WTProfile](docs/Get-WTProfile.md)\n* [Get-WTReleaseNote](docs/Get-WTReleaseNote.md)\n* [Import-WTProfile](docs/Import-WTProfile.md)\n* [Install-WTRelease](docs/Install-WTRelease.md)\n* [New-WTProfile](docs/New-WTProfile.md)\n* [Open-WTDefault](docs/Open-WTDefault.md)\n* [Set-WTDefaultProfile](docs/Set-WTDefaultProfile.md)\n* [Test-IsWTPreview](docs/Test-IsWTPreview.md)\n* [Test-WTVersion](docs/Test-WTVersion.md)\n\n### Installing Windows Terminal\n\nYou can install the latest stable or preview release of Windows Terminal using the packages available on GitHub.\n\n```powershell\nInstall-WTRelease [-preview]\n```\n\nThe `Install-WTRelease` function has an alias of `Install-WindowsTerminal`.\n\n:warning: You can't install a version from within Windows Terminal because files will be in use. Close Windows Terminal and run `Install-WTRelease` in a traditional PowerShell window.\n\n### Displaying Key Bindings\n\nKeeping track of all the possible keyboard shortcuts or keybindings can be difficult. `Get-WTKeyBinding` will go through all defined keybindings and display them.\n\n```powershell\nPS C:\\\u003e Get-WTKeyBinding\n\n   Source: Defaults\n\nAction               ActionSettings                           Keys\n------               --------------                           ----\ncloseWindow                                                   alt+f4\ntoggleFullscreen                                              alt+enter\ntoggleFullscreen                                              f11\ntoggleFocusMode\ntoggleAlwaysOnTop\nopenNewTabDropdown                                            ctrl+shift+space\nopenSettings                                                  ctrl+,\nopenSettings         target = defaultsFile                    ctrl+alt+,\nfind                                                          ctrl+shift+f\ntoggleRetroEffect\n...\n\nSource: Settings\n\nAction               ActionSettings                           Keys\n------               --------------                           ----\ncopy                 singleLine = False                       ctrl+c\npaste                                                         ctrl+v\nfind                                                          ctrl+shift+f\nsplitPane            split = auto;splitMode = duplicate       alt+shift+d\nnewTab               profile = Ubuntu                         ctrl+shift+u\nsplitPane            split = auto;profile = PS7 No            ctrl+shift+\u003e\n                     Profile;startingDirectory =\n                     C:\\;tabTitle = PS7 Clean\nsplitPane            split = auto;profile = Windows           ctrl+shift+\u003c\n                     PowerShell No Profile;startingDirectory\n                     = C:\\;tabTitle = PS Clean\nopenTabColorPicker                                            ctrl+/\n```\n\nYou can also select a specific action:\n\n```poweshell\nPS C:\\\u003e Get-WTKeyBinding -Action *font* | Format-List\n\nSource: Defaults\n\n\nAction         : adjustFontSize\nActionSettings : delta = 1\nKeys           : ctrl+=\n\nAction         : adjustFontSize\nActionSettings : delta = -1\nKeys           : ctrl+-\n\nAction         : resetFontSize\nActionSettings :\nKeys           : ctrl+0\n```\n\n### Getting Current Settings\n\nUse `Get-WTCurrent` to display the settings for the current PowerShell session in Windows Terminal.\n\n![Get-WTCurrent](assets/wtcurrent.png)\n\n### Tracking Windows Terminal Releases\n\nBecause `Windows Terminal` can silently update, it may be awkward to know if you are running a new version. You might use the `Test-WTVersion` command in your PowerShell profile script like this:\n\n```powershell\nif ( $env:wt_session -AND (Test-WTVersion)) {\n    Write-Host \"A newer version of Windows Terminal is now installed.\" -foreground Yellow\n    Start-Process https://github.com/microsoft/terminal/releases\n}\n```\n\nOn a related note, you can also use `Get-WTReleaseNote,` which will get the latest release information from the `Windows Terminal` GitHub repository. If you are running PowerShell 7.x, you can pipe the command to `Show-Markdown`.\n\n```powershell\nGet-WTReleaseNote | Show-Markdown -UseBrowser\n```\n\nThe document will have links to any referenced issues.\n\nYou can also use [Get-WTCurrentRelease](docs/Get-WTCurrentRelease.md) to get a quick peek at the latest online version and your locally installed version.\n\n```powershell\nPS C:\\\u003e Get-WTCurrentRelease\n\nName                        Version       Released             LocalVersion\n----                        -------       --------             ------------\nWindows Terminal v1.13.1143 v1.13.11431.0 5/24/2022 5:01:48 PM 1.13.11432.0\n```\n\n### Windows Terminal Processes\n\nThe `Get-WTProcess` command will get all processes associated with your Windows Terminal process. The output is a standard `System.Diagnostics.Process` object, but the default formatting has been customized to highlight the current PowerShell process.\n\n![Get-WTProcess](assets/wtprocess-ansi.png)\n\n`Get-WTProcess` has an alias of `gwtp`.\n\n## Global Variables\n\nTo make it easier to see either default settings or your custom settings, when you import this module, it will define 3 global variables. Assuming, of course, that you have `Windows Terminal` installed and are using `settings.json`.\n\n### WTSettingsPath\n\nThe path to `settings.json` is buried in your `%AppData%` folder. You can use `$WTSettingsPath` as a placeholder. Yes, you can easily open the file from `Windows Terminal`, but there may be other things you want to do with the path information.\n\n### WTDefaults\n\nYou can use `$WTDefaults` as an object to view any number of default settings. Use `Open-WTDefaults` if you want to open the file in your code editor.\n\n```powershell\nPS C:\u003e\\ $WTDefaults | Select-Object -property initial*\n\ninitialCols initialRows\n----------- -----------\n        120          30\n```\n\nWhen you import the module, it will also create a variable called `$WTDefaultsPath,` which points to the `defaults.json` file. The variable makes it easier if you want to do something with it like make a copy. If you need to view the file, you can use the [Open-WTDefault](docs/Open-WTDefault.md) command.\n\n\u003e If you have a preview release also installed, this variable will have two objects.\n\n### WTSettings\n\nThe last object is a customized version of the data in `settings.json`. `$WTSettings` should make it easier to see your settings.\n\n```powershell\nPS C:\\\u003e $wtsettings.profiles.list | Where-Object hidden\n\nguid       : {b453ae62-4e3d-5e58-bget989-0a998ec441b8}\nhidden     : True\nuseAcrylic : False\nname       : Azure Cloud Shell\nsource     : Windows.Terminal.Azure\n\nguid   : {574e775e-4f2a-5b96-ac1e-a2962a402336}\nhidden : True\nname   : PowerShell\nsource : Windows.Terminal.PowershellCore\n\nguid   : {6e9fa4d2-a4aa-562d-b1fa-0789dc1f83d7}\nhidden : True\nname   : Legacy\nsource : Windows.Terminal.Wsl\n\nguid   : {c6eaf9f4-32a7-5fdc-b5cf-066e8a4b1e40}\nhidden : True\nname   : Ubuntu-18.04\nsource : Windows.Terminal.Wsl\n```\n\nThe object includes a few additional properties.\n\n![wtsettings](assets/wtsettings.png)\n\nThe `LastUpdated` value is when `settings.json` was last revised. The `LastRefresh` value indicates when this object was created. Because you might modify your settings, after importing this module, there needed to be a mechanism to refresh the data. The custom object has a `Refresh()` method you can run at any time.\n\n```powershell\nPS C:\\\u003e $WTSettings.refresh()\n```\n\nThe method doesn't write anything to the pipeline.\n\n_A quick note on the `settings` and `default` objects. The JSON standard does not recognize comments, yet they are used in `Windows Terminal` settings files. You can see them with leading // characters. To avoid errors when converting the JSON to objects, these comments must be stripped out of the content. The clean-up process is done with a regular expression. PowerShell 7 is more forgiving if it detects comments. Windows PowerShell will refuse to convert the content from JSON. Although the module can handle JSON comments, the recommendation is that if you are using comments, that you insert a space after the leading slashes like this:  `// this is a comment`._\n\n## Windows Terminal Profiles\n\nBeginning with version 1.14.0 of this module, you can use PowerShell functions to manage Windows Terminal profiles instead of relying on the module variables like `$wtsettings`.\n\n### Getting Windows Terminal Profiles\n\nYou can use [Get-WTProfile](docs/Get-WTProfile.md) to return all defined Windows Terminal Profiles. The default behavior is to get all non-hidden profiles. The default profile will be highlighted in green.\n\n![get-wtprofile](assets/get-wtprofile.png)\n\nThe command displays formatted results. But there are other properties you can view.\n\n![wtprofile properties](assets/get-wtprofile-properties.png)\n\nIf you opt to view hidden profiles as well, those will be highlighted in red or at least whatever is close to red depending on your color scheme.\n\n![hidden wtprofiles](assets/get-wtprofile-hidden.png)\n\n### Set Default Profile\n\nUse [Set-WTDefaultProfile](docs/Set-WTDefaultProfile.md) to assign a profile from the PowerShell prompt. The easiest approach is to use `Get-WTProfile` to select a single profile and pipe that to the function.\n\n![set-wtdefaultprofile](assets/set-wtdefaultprofile.png)\n\n### Creating a New Profile\n\nYou can use [New-WTProfile](docs/New-WTProfile.md) to create a new profile. The command parameters will set the most commonly used profile settings. You can manually adjust the profile after it has been created.\n\n```powershell\nNew-WTProfile -Name CMD -CommandLine cmd.exe -TabTitle Windows -CursorShape vintage -StartingDirectory \"%WINDIR%\"\n```\n\nNote that some values are case-sensitive. Use tab-completion wherever it is enabled for command parameters. The new profile will be inserted at the beginning of the profile list. You will need to manually edit the settings file to re-order profiles.\n\n### Exporting Profiles\n\nFor backup or testing purposes, you may want to export your custom Windows Terminal profiles with [Export-WTProfile](docs/Export-WTProfile.md). The default is to export all profiles with a commandline property. This command will not export built-in profiles like Azure Cloud Shell. You can also specify profiles to export. Wildcards are permitted.\n\n![export-profile](assets/export-wtprofile.png)\n\nThe export path must be a Json file.\n\n### Importing Profiles\n\nOnce you have an export file, you can use [Import-WTProfile](docs/Import-WTProfile.md) into your current settings. The profile name must not already exist. It is assumed the guids you are importing will be unique. Unlike using `New-WTProfile` the import process will set all profile settings that you exported.\n\n![import-profile](assets/import-wtprofile.png)\n\nProfiles with duplicate names will be skipped.\n\n## Windows Terminal Color Schemes\n\n`Get-WTColorScheme` is designed to show you the defined color schemes. You can select color schemes by name, including the use of wildcards, or use tab-completion. If you omit a name, the default is to get all color schemes.\n\n![get-wtcolorscheme](assets/get-wtcolorscheme.png)\n\nThe output will include a sample property formatted using the ANSI equivalent. This allows you to preview a scheme in your terminal session. Some schemes might have different definitions for a color like `red`.\n\n![compare color schemes](assets/compare-color-scheme.png)\n\n## Known Issues\n\nThe Pester tests for this module will most likely fail when run under Pester 5.x. They are designed for Pester version 4.10.1 and need to be revised to meet the latest Pester test format.\n\n## Future Versions\n\nIf you have any suggestions for enhancements or bug reports, please use the [Issues](https://github.com/jdhitsolutions/WTToolbox/issues) section of this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdhitsolutions%2Fwttoolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdhitsolutions%2Fwttoolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdhitsolutions%2Fwttoolbox/lists"}