search

mkht / pspm

PowerShell Package Manager
MIT License
13 stars 1 forks source link

readme

pspm - PowerShell Package Manager

pspm is the management tools for PowerShell modules.
You can manage PowerShell modules npm like commands.

Requirements

Testing platforms:
Windows 11 Pro x64 22H2 with PowerShell 5.1 & PowerShell 7.3.1
macOS Monterey 12.6 with PowerShell 7.3.1

Installation

You can install pspm from PowerShell Gallery.

Install-Module -Name pspm

Option: Update PowerShellGet

We strongly recommend using the latest PowerShellGet module to improve compatibility and stability.
To update PowerShellGet use the following command and restart PowerShell. 

Install-Module PowerShellGet -Force -AllowClobber

Usage

Install & Import Modules

The command pspm install will download a module from PSGallery. 

pspm install '<Module Name>'

This will create the Modules folder in the current directory and will download the module to that folder, then import it to the current PS session.

Tips: Specify the Module version

If you want to install specific version of the Module.
You can specify the Module name with version or semver range syntax. 

pspm install '<Module Name>@<Version>'  # e.g) pspm install 'Pester@4.1.0'

Tips: Specify the repository

If you want to install the module from specific repository (like Private repository)
You can specify the PSRepository name.
(You should register repositories before. See Microsoft docs)

pspm install '@<Repository Name>/<Module Name>'  # e.g) pspm install '@PrivateRepo/MyModule'

Tips: Get modules from GitHub :octocat:

You can download modules from GitHub repos.
Just <user>/<repo-name> or <user>/<repo-name>#<ref>, or <user>/<repo-name>#<ref>::path/to/subdir.
<ref> as branch or commit-hash or Tag 

pspm install '<user>/<repo-name>'
pspm install '<user>/<repo-name>#<ref>'
pspm install '<user>/<repo-name>#<ref>::path/to/subdir'
# e.g) pspm install 'pester/Pester#7aa9e63'

You can specify Credential or GitHubToken If you want to get modules from private repos.
Also, if an environment variable GITHUB_TOKEN is present, pspm uses it as GitHub Personal Access Token.
(Priority: Credential > GitHubToken > GITHUB_TOKEN)

# Authenticate with Credential (username & password)
pspm install '<user>/<private-repo-name>' -Credential (Get-Credential)

# Authenticate with Personal Access Token
# You should convert token to [SecureString]
$SecureToken = ConvertTo-SecureString '<plain-token>' -AsPlainText -Force
pspm install '<user>/<private-repo-name>' -GitHubToken $SecureToken

Tips: Install multiple Modules at once

If you want to install multiple modules at once or manage modules as code.
You can create package.json and run the pspm install without module name.

If there is a package.json file in the working directory, pspm installs all modules in the list.

About package.json, please refer the section below.

Option: Global installation

Install a module as global.
Module will save to the $env:ProgramFiles\WindowsPowerShell\Modules (on Windows)

pspm install '<Module Name>' -Global
pspm install '<Module Name>' -g
pspm install '<Module Name>' -Scope Global

Option: User installation

Install a module to current user profile.
Module will save to the $env:UserProfile\WindowsPowerShell\Modules (on Windows)

pspm install '<Module Name>' -Scope CurrentUser

Option: Clean installation

When -Clean switch specified, pspm will remove ALL modules in the Modules folder before install process. 

pspm install '<Module Name>' -Clean
# WARNING: -Clean option will remove all modules in the Modules folder, NOT just the specified.

Option: Disable modules import

pspm install will import modules automatically after install.
If you don't like this behavior, Specify -NoImport switch. 

pspm install '<Module Name>' -NoImport

Update Modules

The command pspm update will update modules. 

pspm update '<Module Name>'   # specify the name of module
pspm update  # with package.json

NOTICE: The pspm update will change package.json to save the new version as the minimum required dependency. If you don't wanna update, use pspm update -Save:$false

Tips: What's the difference between install and update ?

Thought as below scenarios.

In this scenario. If you run the command pspm install 'Example@1.x', pspm will NOT update the module that because 1.0.0 is satisfied 1.x.
But if you run pspm update 'Example@1.x', pspm will update the Example to 1.2.0.

Uninstall Modules

To remove a module from your Modules folder, use:

pspm uninstall '<Module Name>'

Run scripts

pspm supports the "scripts" property of the package.json. 

pspm run '<Script Name>'
pspm run '<Script Name>' -Arguments [Object[]]  #with arguments
pspm run '<Script Name>' -IfPresent  #run only when the scripts exist
#aliases: pspm run-script

Special terms

You can omit run when running a script with some special words. (start, restart, stop, test)

pspm start    # = pspm run start
pspm restart  # = pspm run restart
pspm stop     # = pspm run stop
pspm test     # = pspm run test

Example

Save package.json that has scripts property like below in the working directory. 

"scripts": {"hello": "echo 'Hello pspm !'"}

To run Hello script, exec the command.

PS> pspm run 'hello'
Hello pspm !

Tips: Use Arguments

You can use custom arguments when executing scripts.

"scripts": {"name": "echo 'Your name is $args[0]'"}
PS> pspm run 'name' -Arguments 'MyName'
Your name is MyName

Tips: Use "config" object

The package.json that has "config" keys. You can use the object as environment variable of pspm_package_config_<key>

"scripts": {"show_port": "echo \"Port: $env:pspm_package_config_port\""},
"config" : {"port": "8080"}
PS> pspm run 'show_port'
Port: 8080

Tips: Invoke script file

You can invoke outer PowerShell script file.

"scripts": {"ps1": ".\\script.ps1"},

Hook scripts

If you want to run a specific script at a specific timing, then you can use a hook script.

Example

"scripts": {
  "preinstall": "echo '(preinstall) run before install'",
  "install": "echo '(install) run after install'",
  "postinstall": "echo '(postinstall) run after install'"
  }
PS> pspm install 'Pester@4.2.0'
(preinstall) run before install
Pester@4.2.0: Downloading module.
Pester@4.2.0: Importing module.
(install) run after install
(postinstall) run after install

package.json

A package.json file:

scripts

You can define script in package.json
Please refer run scripts 

"scripts": {"hello": "echo 'Hello pspm !'"}

config

define environment variable for run-scripts.
Please refer run scripts 

"config": {"port": "8080"}

dependencies

To specify the modules your project depends on, you need to list the modules you'd like to use in your package.json file. 

  "dependencies": {
    "<Module name 1>": "<Version>",
    "<Module name 2>": "<Version>"
  }

Specifying Module Versions

You can use npm-semver syntax for specifying versions.

Example

This is valid package.json sample.

{
  "scripts": {
    "hello": "echo 'hello pspm'",
    "show_port": "echo \"Port: $env:pspm_package_config_port\""
  },
  "config": {"port": "8080"},
  "dependencies": {
    "Pester": "4.x",
    "AWSPowerShell": "3.3.283.0",
    "PSSlack": ">=0.1.0"
  }
}

Change log