Portal

Portal is a PowerShell module that contains a collection of functions for managing and opening remote connections from your terminal.

Think of Portal as a very basic version of mRemoteNG or MobaXterm, integrated directly into your shell...

---

Table of contents:

• Portal
  • Installation
    • Install from PowerShell Gallery
    • Get released versions
    • Build from Source
  • Usage
    • Prepare your environment
    • Create an inventory file
    • Add a client
    • Add a connection
    • Open a connection
    • Get help
  • License
  • Support

---

Installation

To install the PowerShell module, follow one of these methods:

• Install from PowerShell Gallery
• Get released versions
• Build from Source

Please note that the module is only available for PowerShell Core (7.1 or later).

Get the latest version of PS Core from the official PowerShell repository.

Install from PowerShell Gallery

The module is published on PowerShell Gallery. See https://www.powershellgallery.com/packages/Portal.

To install it, run:

Install-Module -Name Portal -Repository PSGallery

Get released versions

Download Portal.zip from the "Releases" page. Extract it to the ~\Documents\PowerShell\Modules\ directory.

Build from Source

1. Unblock downloaded scripts (optional)

   Get-ChildItem -Filter *.ps1 | Unblock-File

2. Build the module

   .\build.ps1 build -Bootstrap

3. Remove any old versions of the module

   Remove-Item "$HOME\Documents\PowerShell\Modules\Portal" -Force

4. Install the freshly built module

   Copy-Item ".\Out\Portal" "$HOME\Documents\PowerShell\Modules\" -Recurse

---

Usage

Prepare your environment

1. Import the module

   Import-Module -Name Portal

2. Get the available commands

   Get-Command -Module Portal

The fastest way to use the module is to import it from your PowerShell profile. Then, each time you will open your PowerShell console, the module will be automatically imported.

We also recommend that you create aliases for the most commonly used commands.

Here is an example of code that you can add to your profile file:

# Add the following lines to your Microsoft.PowerShell_profile.ps1 file
Import-Module -Name Portal
New-Alias -Name connect -Value Open-Portal

Feel free to use your own aliases!

Create an inventory file

First, you need to create an inventory file, which stores your configuration.

Use New-PortalInventory to create the inventory file. Simply run:

New-PortalInventory

By default, the inventory file is created as %APPDATA%\Portal\inventory.json.

To use a custom path, run:

Set-PortalInventory "C:\path\to\your\inventory.json"

The inventory uses the JSON format, do not forget the file extension.

Add a client

Clients are defined programs that are interpreted and executed when you open a connection.

To add a client, use Add-PortalClient. For instance:

Add-PortalClient -Name MySSH -Executable "ssh.exe" -Arguments "-l <user> -p <port> <host>" -DefaultPort 22 -DefaultScope Console -Description "My first SSH client"

Find examples here.

The -Arguments parameter takes a tokenized string which represents the arguments passed to the executable.

Some tokens must be present in this string.

Token	Required	Description
<host>	Yes	Name of the remote host.
<port>	Yes	Port to connect to on the remote host.
<user>	No	Name of the user to log in with. If set, Open-Portal will ask for a username at each execution.

The -Scope parameter defines in which scope a connection will be opened by default.

Scope	Description
Console	Open the connection process in the current console. (Default)
External	Open the connection process as an independant process (external window).
Undefined	Undefined scope. A scope must be specified when the connection is opened.

Add a connection

To add a connection, use Add-Portal. For instance:

Add-Portal -Name Perseverance -Hostname perseverance.mars.solarsys -DefaultClient MySSH -DefaultUser nasa -Description "My connection to the Perseverance Rover"

Press TAB key to autocomplete the name of the client.

Open a connection

To open a connection, use Open-Portal. For instance:

Open-Portal Perseverance

Press TAB key to autocomplete the name of the connection.

Get help

Read help files in docs/cmdlet-help.

You can also use the Get-Help Cmdlet to obtain more information about a command.

---

License

Portal is released under the terms of the MIT license. See LICENSE or https://opensource.org/licenses/MIT.

Support

If you have any bug reports, log them on the issue tracker.

If you have some suggestions, please don't hesitate to contact me (find email on my GitHub profile).