PowerShell Modules Repository

Cloudsmith provides public & private repositories for PowerShell Modules

A PowerShell module is a package that contains PowerShell members, such as cmdlets, providers, functions, workflows, variables, and aliases. The members of this package can be implemented in a PowerShell script, a compiled DLL, or a combination of both.

For more information on PowerShell modules, please see:

• PowerShell Documentation: The official website for PowerShell
• PowerShell Modules Documentation: The official documentation for PowerShell Modules
• PowerShell Gallery: Central Repository for public PowerShell Modules
• PowerShell Module Browser: Browser for Microsoft PowerShell Modules

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

PowerShell modules use the NuGet package format, and Cloudsmith NuGet Feeds are fully compatible as a PowerShell Module Repository.

Upload a package

The endpoint for the PowerShell Modules API is:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2

Create a PowerShell Module

PowerShell Modules combine several PowerShell functions into a single reusable and easily sharable resource. You can put many files, such as .DLLs and tools, in a module but the absolute minimum is a .psm1 file.

PowerShell Module Manifest

A PowerShell Module manifest is a PowerShell data file (.psd1) that contains information about the module like the version number and exported variables.

Note

PowerShell Module manifests are required to publish a module to a repository.

To create a PowerShell Module Manifest, use the New-ModuleManifest command:

New-ModuleManifest -Path TARGET_PATH -Author AUTHOR_NAME -Description "MODULE_DESCRIPTION" 

Upload a package via native PowerShell Module tooling

You can upload your package using Publish-Module.

PowerShell requires that publish locations be explicitly added (with authentication credentials) via Register-PSRepository prior to publishing:

$credential = New-Object PSCredential('USERNAME',$(ConvertTo-SecureString 'API-KEY' -AsPlainText -Force))

Register-PSRepository -Name 'NAME' -SourceLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -PublishLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -InstallationPolicy 'trusted' -Credential $credential

Then you can publish a module with:

Publish-Module -Path 'path/to/Your.Module' -Repository 'NAME' -NugetApiKey 'API-KEY'

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command-Line Interface .

The command to upload a PowerShell Module via the Cloudsmith CLI is:

cloudsmith push nuget OWNER/REPOSITORY MODULE_NAME-MODULE_VERSION.nupkg

Example:

cloudsmith push nuget demo/examples-repo your-module-1.2.3.nupkg

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Download / Install a Package

Setup

You can set up the source ahead of time, using Register-PackageSource and Register-PSRepository:

Public Repositories

Register-PackageSource -Name 'NAME' -Location 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -Trusted -ProviderName NuGet

Register-PSRepository -Name 'NAME' -SourceLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -InstallationPolicy 'trusted'

For example:

Register-PackageSource -Name 'cloudsmith' -Location 'https://nuget.cloudsmith.io/demo/examples-repo/v2/' -Trusted -ProviderName NuGet

Register-PSRepository -Name "cloudsmith" -SourceLocation "https://nuget.cloudsmith.io/demo/examples-repo-public/v2" -InstallationPolicy 'trusted'

Private Repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

In order to authenticate to a private Cloudsmith repository, you must first create a PSCredential object that you then use with Register-PackageSource and Register-PSRepository:

$credential = New-Object PSCredential('token',$(ConvertTo-SecureString 'TOKEN' -AsPlainText -Force))

Register-PackageSource -Name 'NAME' -Location 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -Trusted -ProviderName NuGet -Credential $credential

Register-PSRepository -Name 'NAME' -SourceLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -InstallationPolicy 'trusted' -Credential $credential

$credential = New-Object PSCredential('USERNAME',$(ConvertTo-SecureString 'PASSWORD' -AsPlainText -Force))

Register-PackageSource -Name 'NAME' -Location 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -Trusted -ProviderName NuGet -Credential $credential

Register-PSRepository -Name 'NAME' -SourceLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -InstallationPolicy 'trusted' -Credential $credential

$credential = New-Object PSCredential('USERNAME',$(ConvertTo-SecureString 'API-KEY' -AsPlainText -Force))

Register-PackageSource -Name 'NAME' -Location 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -Trusted -ProviderName NuGet -Credential $credential

Register-PSRepository -Name 'NAME' -SourceLocation 'https://nuget.cloudsmith.io/OWNER/REPOSITORY/v2/' -InstallationPolicy 'trusted' -Credential $credential

Install a Package

Then to install a package, you use Install-Module

Public Repositories

Install-Module -Name "MODULE_NAME"  -Repository NAME

For Example:

Install-Module -Name "MyModule"  -Repository cloudsmith

Private Repositories

Install-Module -Name 'MODULE_NAME' -Repository NAME -Credential $credential

For Example:

Install-Module -Name "MyModule"  -Repository cloudsmith -Credential $credential