PSTuiTools

This PowerShell 7 module contains a set of tools and sample scripts written using the open-source Terminal.Gui toolkit. These types of commands are often referred to as a tui (terminal user interface). These commands are designed to be run in the traditional PowerShell console and should run cross-platform, where the underlying PowerShell commands, e.g. Get-Service, are supported.

You are welcome and encouraged to use the source code as reference material for your projects. The sample TUIs are completely functional, but should not be considered production-ready. This module is intended as a reference framework and not something to implement in production.

Installation

You can install the module from the PowerShell Gallery:

Install-PSResource PSTuiTools

The module requires a PowerShell 7. Some of the TUI examples will work cross-platform. If there is a platform restriction, you will get a warning.

Installation will include the required third-party assemblies.

Terminal.Gui

The samples in this module are built using version 1.19.0 of the open-source Terminal.Gui. This has a dependency on the NStack.Core package. Documentation for v1 can be found at https://gui-cs.github.io/Terminal.GuiV1Docs/.

This version was selected because it is the most recent stable release, although it is also the last release in the v1 branch.

The file version of the Terminal.Gui.dll will show 1.0.0.0 but the product version is 1.19.0.

Terminal.Gui v2

Version 2 of Terminal.Gui is currently in development. The core features are supposedly set, but the current release is only at the alpha stage. I am hesitant to create TUI samples that might break with new pre-releases. There are significant changes in v2. When it is officially released, the plan is to update this module to use the latest stable version.

If you want to create TUIs using version 2, you can find reference documentation at https://gui-cs.github.io/Terminal.Gui/. One feature I am looking forward to is removing the NStack dependency.

Potential Assembly Conflicts

There are other PowerShell modules you might have installed that also use Terminal.Gui. A prime example is the Microsoft.PowerShell.ConsoleGuiTools which provides the Out-ConsoleGridView command. This project uses v1.16.0 of the Terminal.Gui assembly. If this module is loaded first, you'll get a warning about the version conflict. I can't guarantee that all TUIs in this module will work as expected. If you load this module first, and then try to load Microsoft.PowerShell.ConsoleGuiTools, you'll get an error about the version conflict and the Out-ConsoleGridView command will not work.

Your best course of action is to choose one module or the other in your PowerShell session. This might require you to restart your PowerShell session.

This module includes code to attempt to mitigate assembly conflicts. I am open to PRs that provide a better solution.

PSTuiTools

The module contains the following commands and features. The TUIs are primarily intended as examples and reference material for you to use in your own projects. All commands include full help.

Get-PSTuiTools

Run Get-PSTuiTools to see a list of available module commands including their aliases and help synopses.

PS C:\> Get-PSTuiTools

   Module: PSTuiTools [v0.6.0]

Name                 Alias         Synopsis
----                 -----         --------
Get-PSTuiTools                     Get sample TUI tools.
Get-TuiCredential    tuicred       Prompt for credentials in a TUI.
Invoke-HelloWorld    HelloWorld    Run a "Hello World" demo.
Invoke-ProcessPeeker ProcessPeeker A TUI process viewer.
Invoke-PSTuiTools    PSTuiTools    Show module commands in a TUI
Invoke-ServiceInfo   ServiceInfo   A TUI for displaying service information.
Invoke-SystemStatus  TuiStatus     Run a system status TUI monitor.
Invoke-TuiColorDemo  TuiColorDemo  Run the TUI color demo.
Invoke-TuiGraphDemo  tuiGraph      Run a demo TUI graph.
Invoke-TuiMp3        tuimp3        Launch a TUI MP3 player.
Invoke-TuiTemplate   TuiTemplate   Run the TUI template script.
Invoke-TuiTreeDemo   tuiTree       Run a TreeView demo TUI.
Save-TuiAssembly                   Download Terminal.GUI and NStack assemblies.

Invoke-PSTuiTools

As an alternative to Get-PSTuiTools, you can run Invoke-PSTuiTools to see the available commands in a TUI. You can select a command to run it and see the help description.

Invoke-HelloWorld

Every project like this needs a Hello World example. This is a simple TUI that displays a label and a button. When the button is clicked, the label text will change. It will revert to the original text after 5 seconds.

This TUI has a PowerSell alias of HelloWorld.

Get-TuiCredential

This TUI will present a form to the user to enter a username and password. When the user clicks the submit button, a PSCredential object will be returned.

$cred = Get-TuiCredential

You can pass a user name as a parameter value from the PowerShell prompt.

This command has an alias of tuicred.

Invoke-ProcessPeeker

This is a sample TUI to display process information and details. Select a process from the list on the left to see details in the panel on the right.

Invoke-ServiceInfo

This TUI will display service information from the specified computer. You can use alternate credentials to connect. You can also filter the services by status.

Invoke-SystemStatus

This is a very complex TUI that displays a variety of system information derived from Get-CimInstance.

This command has an alias of TuiStatus You can specify a computer and alternate credentials from the prompt.

PS C:\> Get-Command Invoke-SystemStatus -Syntax

Invoke-SystemStatus [[-Computername] <string>] [-Credential <pscredential>] [-WindowColor <Color>] [<CommonParameters>]

Or enter new credentials if you want to change the computer.

The TUI includes an optional automatic refresh feature. You should set the refresh value (in seconds) first, then click the Start Timer button. If you use a timer and want to change the computer, you should stop the timer first, then change the computer and start the timer again.

You can always refresh the information manually by clicking the Refresh button.

Invoke-TuiMp3

This function will launch a simple TUI-based audio player. You can specify the path to a .mp3 or .m4a file to play, or open a file from the menu. You can set a default library folder to open to simplify navigation. Use the buttons to control playback. Selected metadata and lyrics will be displayed if found in the MP3 file.

You can control the volume by clicking the volume bar, the +/- buttons, or using Ctrl+Up or Ctrl+Down.

Beginning with v0.5.0, the player will keep a most recently played list. As new songs are played, they will be added to the list. The maximum number of entries is 10. After that, the oldest entry is removed. The list is persisted in a file called tuiMp3-most-recent.txt under $HOME. If you uninstall the module, you will need to manually remove the file.

Version 0.6.0 and later of the module allow you to set the TUI foreground and background colors. Use tab-completion to see the possible color values.

Note that there is a limitation in the file dialog. You cannot load a file if it has a comma in the name because it gets processed as an array. This is a limitation in Terminal.Gui. However, you can specify a file with commas in the name with the FilePath parameter when launching the TUI Mp3 player.

This function uses the TagLibSharp library to read audio media metadata.

Invoke-TuiColorDemo

You can use this TUI to experiment with different color combinations. The TUI will dynamically update sample code which you should be able to copy and paste into your project.

Invoke-TuiTreeDemo

This command will run a sample TUI that uses the TreeView control. It will display a specified path as a tree showing files and folders. You can control the depth. The default is 4. The more levels, the longer it will take to open the TUI, especially for large folders.

Default path is $HOME, but you can specify a folder.

You can manually click in the tree to expand and collapse nodes or use the toggle button. Details from the selected tree item will be displayed in another detail tree on the right. You might see different detail information depending on the file.

If you right click a file in the main tree, depending on the file extension, the contents will be displayed in a dialog box. Most text files should be displayed.

Enter a new path in t