Skip to main content

PowerShell

PowerShell (native c8y binary)​

  1. Clone the addons repository containing the install script, views and some example templates.

    git clone https://github.com/reubenmiller/go-c8y-cli-addons.git "$HOME/.go-c8y-cli"
    info

    This repository is not strictly required to run c8y however it makes is much more useful as it provides some default views and templates to get the most out of c8y. The defaults also show you how you can create your own custom views.

  2. Install go-c8y-cli binary

    & "$HOME/.go-c8y-cli/install.ps1"
    tip

    If the following warning is displayed when you try to run the install.ps1 script

    File C:\Users\myuser\.go-c8y-cli\install.ps1 cannot be loaded because running scripts is disabled on this system...

    Then, open up a new powershell console but set the ExecutionPolicy to remotesigned (or bypass), then you can all the run the script again.

    powershell -ExecutionPolicy remotesigned
    tip

    You can install go-c8y-cli into a shared folder (i.e. C:\tools\cumulocity)

    .\install.ps1 -InstallPath C:\tools\cumulocity -UserHome C:\tools\cumulocity -SkipVersionCheck

    # Or if you want to edit the global powershell profile for all users, but this requires administrator rights!
    .\install.ps1 -InstallPath C:\tools\cumulocity -UserHome C:\tools\cumulocity -SkipVersionCheck -ProfilePath $PROFILE.AllUsersAllHosts

  3. Verify that the c8y binary is executable and can be found on the command line 

    Get-Command c8y
    Output
    CommandType    Name       Version    Source
    -----------    ----       -------    ------
    Application    c8y.exe    0.0.0.0    C:\Users\myusername\bin\c8y.exe
    tip

    Try closing your console and re-opening it so you can be sure that your setup will work next time

  4. Now go to the Getting started section for instructions how to use it

Updating c8y​

If you installed the native c8y binary for powershell using the instructions above, then you can update to the latest version by running:

update-c8y
tip

The update-c8y function is included in the addons file, $HOME/.go-c8y-cli/shell/c8y.plugin.ps1, which should have been added to your $PROFILE file during the installation.

Alternative installation methods​

caution

PSc8y is no longer required to get the best out of go-c8y-cli, so it recommended to use the native c8y binary instead.

Prerequisites​

PowerShell (Core) 7 is available on many operating systems (i.e. Windows, MacOS, Linux). Following the installation guide to install it on your machine.

caution

PSc8y no longer supports PowerShell 5. Users should install PowerShell 7 (aka pwsh) as it provides a lot of benefits and is also supported on multiple platforms (linux, MacOS and Windows).

If you still don't want to or can't install PowerShell 7 then install the native go-c8y-cli binary.

Installing PSc8y​

  1. Open a PowerShell (pwsh) console

    pwsh
    Windows Users

    If you get an error regarding the Execution policy when installing or importing PSc8y, then you will have to start a new powershell disabling the execution policy.

    pwsh -ExecutionPolicy bypass

    More information on PowerShell's execution policy can be found on the Microsoft website

  2. Install PSc8y module from PSGallery

    Install-Module PSc8y -AllowPrerelease -Repository PSGallery -AllowClobber -Scope CurrentUser

  3. Import the module

    Import-Module PSc8y

  4. Now go to the Getting started section for instructions how to use it

Updating PSc8y​

Once the PSc8y PowerShell module has been installed, then it can be updated from within PowerShell itself assuming it was installed as per the "Installing PSc8y" section above.

  1. Update to the latest version

    Update-Module PSc8y

  2. Import the updated module

    Import-Module PSc8y -Force

  3. Check the new version

    Get-Module PSc8y
    ModuleType Version    Name    ExportedCommands
    ---------- -------    ----    ----------------
    Script     2.0.0      PSc8y   {Add-PowershellType, Add-...
    info

    The version number does not show the pre-release version information.

Downloading using Save-Module​

The PSc8y module can be downloaded manually using Save-Module. This has the advantage over Install-Module as you can control where the module is saved to.

info

Install-Module does not allow you to control where the modules are installed. By default the target folder is inside your home directory, however if you have your home folder synced automatically to Microsoft OneDrive then you might run into problems as PSc8y contains executables (i.e. .exe files).

  1. Create a folder where you want to store PSc8y

    mkdir ~/PSModules

  2. Download the PSc8y Module to the folder ~/PSModules

    Save-Module -Name PSc8y -AllowPrerelease -Repository PSGallery -Path ~/PSModules
    tip

    Save-Module also accepts -RequiredVersion where you can specify an exact version instead of the latest.

  3. Import PSc8y

    Import-Module ~/PSModules/PSc8y -Force
    tip

    You can the ~/PSModules folder to the $env:PSModulePath variable so that you can use Import-Module without having to specify the module location each time.

    The best way to do this is by adding the following to your PowerShell profile. This can be open by editing the path stored in the $PROFILE variable. If the file does not exist, just create it in the specified location.

    $env:PSModulePath = (Resolve-Path "~/PSModules").Path + ";" + $env:PSModulePath