Getting Started

Prerequisites

Be sure to satisfy all the requirements listed here.

Installing Modules

Start a PowerShell session:
1. On Windows, launch PowerShell from the Start Menu.
2. On Linux or MacOS, run pwsh from a shell prompt:
```
$ pwsh

PowerShell 7.1.0
Copyright (c) Microsoft Corporation. All rights reserved.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/username>
```
To install all OCI modules, install the base module:

Install-Module OCI.PSModules

Note

Uninstalling the OCI.PSModules module will not uninstall other OCI modules. To uninstall a specific OCI module installed by this module, the OCI.PSModules module will have to be uninstalled first.
You can install just the modules for an individual service. Cmdlets corresponding to each OCI service supported by OCI Modules for PowerShell are packaged into an individual Powershell module named OCI.PSModules.<ServiceName>.
Continue to either Installing from PowerShell Gallery or Installing from GitHub.

Installing from PowerShell Gallery

By default, PowerShell Gallery ("PS Gallery") is configured as a PSRepository. This can be verified by running the Get-PSRepository command:

PS /> Get-PSRepository
 
Name                      InstallationPolicy   SourceLocation
----                      ------------------   --------------
PSGallery                 Untrusted            https://www.powershellgallery.com/api/v2

You can set PS Gallery as a trusted repository to avoid prompts every time you attempt to install a module from PS Gallery:
```
PS /> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
```
PowerShell modules that correspond to a supported OCI service are called service modules. To install a service module run the Install-Module command. This example installs the service module for the OCI Identity service:
```
PS /> Install-Module -Name OCI.PSModules.Identity
```
Note

Each service module depends on the OCI.PSModules.Common (Common Module), which offers functionality common to all service modules. Installing a service module will also install the corresponding version of OCI.PSModules.Common for that service module.
Installed modules can be found in the path specified by the $Env:PSModulePath environment variable, or by running the Get-Module command with the ListAvailable parameter.
```
PS /> Get-Module -ListAvailable
```

Installing from GitHub

To install the OCI PowerShell modules from GitHub:

Download the latest OCI Modules artifacts and extract them into a local directory.
Note

Cmdlets corresponding to each OCI service supported by OCI Modules for PowerShell are packaged into an individual Powershell module named OCI.PSModules.<ServiceName>.
Register the extracted directory as the local PowerShell repository:
```
PS /> Register-PSRepository -Name "LocalRepo" -SourceLocation <extractedlocation>
```
Find the modules available in the local repository:
```
PS /> Find-Module -Repository "LocalRepo"
```
Install a specific module:
```
PS /> Install-Module -Name OCI.PSModules.Objectstorage -Verbose -Repository LocalRepo
```
Note

Each service module depends on the OCI.PSModules.Common (Common Module), which offers functionalities common to all service modules. Installing a service module will also install the corresponding version of OCI.PSModules.Common for that service module.
Installed modules can be found in the path specified by the $Env:PSModulePath environment variable, or by running the Get-Module command with the ListAvailable parameter.
```
PS /> Get-Module -ListAvailable
```

Installing with Yum

If you are using Oracle Linux version 7.x, the OCI PowerShell Modules packages can be installed with yum.

To install the OCI PowerShell modules using yum:
```
$ sudo yum install oci-powershell-modules
```
Start a PowerShell Session and register the downloaded directory /usr/lib/dotnet/NuPkgs as a local PowerShell repository using the following command:
```
$ pwsh
PS /> Register-PSRepository -Name "LocalRepo" -SourceLocation /usr/lib/dotnet/NuPkgs
```
Find the modules available in the local repository using the following command:
```
PS /> Find-Module -Repository "LocalRepo"
```
Install a specific module:
```
PS /> Install-Module -Name OCI.PSModules.Objectstorage -Verbose -Repository LocalRepo
```
Note

Each service module depends on the OCI.PSModules.Common (Common Module), which offers functionalities common to all service modules. Installing a service module will also install the corresponding version of OCI.PSModules.Common for that service module.
Installed modules can be found in the path specified by the $Env:PSModulePath environment variable, or by running the Get-Module command with the ListAvailable parameter.
```
PS /> Get-Module -ListAvailable
```

Setup

Follow these installation steps if you haven't installed the required modules.

Before invoking cmdlets in OCI Modules, you need to set up the configuration file, and then optionally import the required modules into a PowerShell session.

Configuration File

A configuration file provides essential configuration information, like user credentials and tenancy OCID. This configuration information is used by the OCI Modules for PowerShell to authenticate and interact with Oracle Cloud services. You can create this file using a setup cmdlet, or manually using a text editor.

Set-OCIClientConfig

The Set-OCIClientConfig cmdlet included in the Common module will walk you through setting up a configuration file. This cmdlet prompts you for information required by the configuration file, including the key pair used to sign API requests.

For more information about how to find the required information, see:

Manual Setup

If you want to set up the API signing key pair manually and write your own configuration file, see SDK and Tool Configuration and Required Keys.

Note

Use the New-OCIClientKeys cmdlet to generate a API signing key pair to include in the configuration file.

Importing Modules

PowerShell will automatically import the module (and its dependencies) into your session the first time you run any command from the installed module. To explicitly import a module, run the Import-Module command.

For example, to import the version 1.0.0 of the Identity service module:

PS /> Import-Module OCI.PSModules.Identity  -RequiredVersion 1.0.0   -Verbose

To find all imported modules in your current PowerShell Session, run the Get-Module command:

PS /> Get-Module
 
ModuleType Name                            ExportedCommands
---------- ----                            ----------------
    Binary OCI.PSModules.Common            {Clear-OCICmdletHistory, Get-OCIClientSession], Get-OCICmdletHisto…
    Binary OCI.PSModules.Identity          {Add-OCIIdentityUserToGroup, Enable-OCIIdentityMfaTotpDevice…

Note

Each service module depends on the OCI.PSModules.Common (Common Module), which offers functionalities common to all service modules. Installing a service module will also install the corresponding version of OCI.PSModules.Common for that service module.

Updating Modules

New versions of the OCI PowerShell modules release weekly. To update the installed OCI PowerShell modules to the latest version, run the Update-Module command.

Note

Before updating any OCI module, you should first uninstall the module. To avoid dependency conflicts when importing modules into PowerShell session, update all installed OCI Modules to the same version.

PS /> Update-Module -Name "OCI.PSModules.*" -Verbose

Uninstalling Modules

To remove any installed module, you can either use the Uninstall-Module cmdlet or delete the module folder located in the path in the $Env:PSModulePath environment variable.

For example:

PS /> Uninstall-Module -Name OCI.PSModules.Identity

Next Steps

Now that you've taken care of installation and setup, you can proceed directly to Working with Cmdlets, or continue to Advanced Concepts.

Oracle Cloud Infrastructure Documentation