### Example CLIPasswordSDK Configuration File Content

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

This is an example of the XML content for the per-user configuration file located at $env:USERPROFILE\AIMConfiguration.xml. The file is automatically created and imported by the CredentialRetriever module.

```xml
<?xml version="1.0" encoding="utf-8"?>
<Objs Version="1.1.0.1">
  <Obj RefId="0">
    <TN RefId="0">
      <T>System.Management.Automation.PSCustomObject</T>
    </TN>
    <MS>
      <S N="ClientPath">D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe</S>
    </MS>
  </Obj>
</Objs>
```

--------------------------------

### CLIPasswordSDK Argument Construction Example

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/invoke-aimclient.md

Demonstrates how command-line arguments are constructed for CLIPasswordSDK.exe, combining Command, Options, and CommandParameters.

```powershell
GetPassword  /p AppDescs.AppID="MyApp" /p Query="Safe=MySafe;Folder=Root;UserName=user1" /o Password,UserName /d #_-_#
```

--------------------------------

### Invoke-AIMClient with Options Parameter

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/invoke-aimclient.md

This example shows how to use the -Options parameter with Invoke-AIMClient, along with specifying the command and command parameters.

```powershell
$result = Invoke-AIMClient `
    -Command 'GetPassword' `
    -Options '' `
    -CommandParameters "/p AppDescs.AppID=`"MyApp`" /p Query=`"Safe=MySafe`" /o Password"
```

--------------------------------

### Install CredentialRetriever Module

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/README.md

Installs the CredentialRetriever module from the PowerShell Gallery and imports it into the current session.

```powershell
# From PowerShell Gallery
Install-Module -Name CredentialRetriever -Scope CurrentUser

# Import module
Import-Module CredentialRetriever
```

--------------------------------

### Install and Import CredentialRetriever Module

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Installs the CredentialRetriever module and imports it into the current session. This is a prerequisite for using the module's cmdlets.

```powershell
# Install module
Install-Module -Name CredentialRetriever

# Import module
Import-Module CredentialRetriever
```

--------------------------------

### Direct Invocation Example (Not Recommended)

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/start-aimclientprocess.md

Demonstrates how to directly invoke Start-AIMClientProcess by manually creating and configuring a System.Diagnostics.Process object. This method is not recommended for general use.

```powershell
# Create and configure process
$Process = New-Object System.Diagnostics.Process
$Process.StartInfo.FileName = "C:\CyberArk\CLIPasswordSDK.exe"
$Process.StartInfo.Arguments = "/p AppDescs.AppID=`"TestApp`" /p Query=`"Safe=TestSafe`" /o Password"
$Process.StartInfo.RedirectStandardOutput = $true
$Process.StartInfo.RedirectStandardError = $true
$Process.StartInfo.UseShellExecute = $false
$Process.StartInfo.CreateNoWindow = $true
$Process.StartInfo.WindowStyle = 'hidden'

# Execute and capture output
$result = Start-AIMClientProcess -Process $Process

if ($result.ExitCode -eq 0) {
    Write-Host "Success: $($result.StdOut)"
} else {
    Write-Host "Error: $($result.StdErr)"
    Write-Host "Exit Code: $($result.ExitCode)"
}
```

--------------------------------

### Get Help for CCP and AIM Functions

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/module-overview.md

Use Get-Help to access full documentation for specific CCP and AIM functions.

```powershell
Get-Help Get-CCPCredential -Full
Get-Help Get-AIMCredential -Full
Get-Help Set-AIMConfiguration -Full
```

--------------------------------

### Install CredentialRetriever Module from PowerShell Gallery

Source: https://github.com/pspete/credentialretriever/blob/master/README.md

Installs the CredentialRetriever module from the PowerShell Gallery. Requires PowerShell 5.0 or above and administrator rights.

```powershell
Install-Module -Name CredentialRetriever -Scope CurrentUser
```

--------------------------------

### Get Help for Get-CCPCredential

Source: https://github.com/pspete/credentialretriever/blob/master/README.md

Retrieves detailed help information for the Get-CCPCredential cmdlet, including parameters, syntax, and examples.

```powershell
Get-Help Get-CCPCredential -Full
```

--------------------------------

### Set AIM Configuration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/types.md

This example demonstrates how to set the ClientPath for the CLIPasswordSDK.exe. The configuration is stored in the script-scoped variable $Script:AIM and persisted to a file.

```powershell
# After running Set-AIMConfiguration
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Access the configuration (script scope, not directly accessible in console)
# This is done internally by the module:
# $clientPath = $Script:AIM.ClientPath
```

--------------------------------

### Verify CredentialRetriever Module Installation

Source: https://github.com/pspete/credentialretriever/blob/master/README.md

Checks if the CredentialRetriever module is available on the local machine after manual installation or installation from the PowerShell Gallery.

```powershell
Get-Module -ListAvailable CredentialRetriever
```

--------------------------------

### Demonstrate Process Execution Result Object

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/types.md

This example shows how to access properties of the PSCustomObject returned by Invoke-AIMClient. It is typically handled internally by the module.

```powershell
# The following is for demonstration; normally this is handled internally
$result = Invoke-AIMClient -CommandParameters "/p AppDescs.AppID=`"TestApp`" /p Query=`"Safe=TestSafe`" /o Password"
Write-Host "Exit Code: $($result.ExitCode)"
Write-Host "Output: $($result.StdOut)"
if ($result.StdErr) {
    Write-Host "Error: $($result.StdErr)"
}
```

--------------------------------

### Using Get-AIMCredential to Retrieve Credentials

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/invoke-aimclient.md

This example demonstrates using the Get-AIMCredential function, which internally calls Invoke-AIMClient. This is the recommended approach for retrieving credentials.

```powershell
# Get-AIMCredential automatically calls Invoke-AIMClient
$cred = Get-AIMCredential -AppID MyApp -Safe MySafe -UserName testuser
```

--------------------------------

### Configure and Get Credentials from Local Credential Provider

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/README.md

Sets up the configuration for the local Credential Provider using Set-AIMConfiguration and then retrieves credentials using Get-AIMCredential. Requires AppID, Safe, and UserName.

```powershell
# First-time setup
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Retrieve credentials
$cred = Get-AIMCredential -AppID MyApp `
    -Safe MySafe `
    -UserName myuser

$password = $cred.Password
```

--------------------------------

### Configure CLIPasswordSDK Path

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Sets the path to the CLIPasswordSDK executable, which is required for the Get-AIMCredential cmdlet. Ensure the path is correct for your installation.

```powershell
# Configure CLIPasswordSDK path (required for Get-AIMCredential)
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"
```

--------------------------------

### Get-AIMCredential - Query with Regex Matching

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

This example demonstrates how to perform a credential query using a regular expression for matching. The 'QueryFormat' parameter is set to 'regexp' to enable regex matching for the 'UserName' property.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -UserName "svc-.*" `
    -QueryFormat regexp

# Constructs command:
# GetPassword /p AppDescs.AppID="YourApp" /p Query="Safe=YourSafe;UserName=svc-.*" /p QueryFormat="regexp" /o Password,PasswordChangeInProcess /d #_-_#
```

--------------------------------

### Get-AIMCredential - Query with Required Properties

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

This example shows how to use Get-AIMCredential to query for credentials and specify which properties should be returned. The 'RequiredProps' parameter is used to list the desired properties.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -UserName YourUser `
    -RequiredProps UserName, Address, Database

# Constructs command:
# GetPassword /p AppDescs.AppID="YourApp" /p Query="Safe=YourSafe;UserName=YourUser" /p RequiredProps="UserName,Address,Database" /o PassProps.UserName,PassProps.Address,PassProps.Database,Password,PasswordChangeInProcess /d #_-_#
```

--------------------------------

### Get-AIMCredential - Simple Query by UserName

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

This example demonstrates how to retrieve credentials using Get-AIMCredential by specifying the AppID, Safe, Folder, and UserName. The function constructs a CLIPasswordSDK command for a simple query.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -Folder Root `
    -UserName YourUser

# Constructs command:
# GetPassword /p AppDescs.AppID="YourApp" /p Query="Safe=YourSafe;Folder=Root;UserName=YourUser" /o Password,PasswordChangeInProcess /d #_-_#
```

--------------------------------

### Using Skip-CertificateCheck via Get-CCPCredential

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/skip-certificatecheck.md

This example shows how Skip-CertificateCheck is automatically invoked when the -SkipCertificateCheck parameter is used with the Get-CCPCredential cmdlet. This is the recommended way to use the functionality.

```powershell
# Skip-CertificateCheck is called automatically when using -SkipCertificateCheck
$cred = Get-CCPCredential -AppID PSScript \
    -Safe PSAccounts \
    -Object PSPlatform-AccountName \
    -URL https://self-signed.cyberark.local \
    -SkipCertificateCheck
```

--------------------------------

### Find PowerShell Module Paths

Source: https://github.com/pspete/credentialretriever/blob/master/README.md

Lists the directories where PowerShell looks for modules. Used to determine where to manually install the CredentialRetriever module.

```powershell
$
env:PSModulePath.split(';')

```

--------------------------------

### Get-AIMCredential - Query with Audit Reason and Timeout

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

This example shows how to include an audit reason and set a request timeout when retrieving credentials. The 'Reason' parameter provides context for the audit log, and 'Timeout' specifies the request duration in seconds.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -UserName YourUser `
    -Reason "Deployment automation" `
    -Timeout 45

# Constructs command:
# GetPassword /p AppDescs.AppID="YourApp" /p Query="Safe=YourSafe;UserName=YourUser" /p Reason="Deployment automation" /p ConnectionParms.Timeout=45 /o Password,PasswordChangeInProcess /d #_-_#
```

--------------------------------

### Direct Invocation of Invoke-AIMClient

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/invoke-aimclient.md

This example shows direct invocation of Invoke-AIMClient. Ensure $Script:AIM.ClientPath is configured before running. It captures the result and checks the ExitCode for success or failure.

```powershell
# Note: Requires $Script:AIM.ClientPath to be configured first
$result = Invoke-AIMClient -CommandParameters "/p AppDescs.AppID=`"TestApp`" /p Query=`"Safe=TestSafe;UserName=testuser`" /o Password"

if ($result.ExitCode -eq 0) {
    Write-Host "Success: $($result.StdOut)"
} else {
    Write-Host "Error: $($result.StdErr)"
}
```

--------------------------------

### CLIPasswordSDK Output Format

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

CLIPasswordSDK returns output as a delimited string. This example shows the format of the output and how it is mapped to property names after being split by the specified delimiter.

```powershell
Property1Value#_-_#Property2Value#_-_#Property3Value#_-_#...
```

```powershell
Password = "MyPassword123"
PasswordChangeInProcess = "false"
UserName = "app_user"
Address = "192.168.1.10"
Database = "postgres_prod"
```

--------------------------------

### Get AIM Credential with Required Properties

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Retrieves credentials using the local AIM provider and specifies additional properties to be returned along with the username and password. Ensure CLIPasswordSDK is configured first.

```powershell
# Must configure CLIPasswordSDK path first
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Retrieve credentials with additional properties
$cred = Get-AIMCredential -AppID MyApp `
    -Safe MySafe `
    -UserName myuser `
    -RequiredProps UserName, Address, Database
```

--------------------------------

### Get CCP Credential with Default Settings

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Retrieves credentials from CyberArk Central Policy Manager (CCP) using default parameters. This is a basic usage example.

```powershell
# Basic query using default parameters
$cred = Get-CCPCredential -AppID MyApp `
    -Safe MySafe `
    -UserName myuser `
    -URL https://cyberark.company.com
```

--------------------------------

### Use with WhatIf

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/set-aimconfiguration.md

Illustrates how to use the -WhatIf parameter with Set-AIMConfiguration to preview the intended configuration change without actually applying it. Note that full -WhatIf support may not be implemented in the function.

```powershell
# Preview what the configuration would do (note: not fully implemented in function)
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe" -WhatIf
```

--------------------------------

### Use Either Credential or UseDefaultCredentials

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Demonstrates the correct usage of authentication parameters, recommending the use of either -Credential or -UseDefaultCredentials, but not both simultaneously.

```powershell
# Good: Use UseDefaultCredentials
$cred = Get-CCPCredential -AppID MyApp -Safe MySafe -Object MyObject \
    -URL https://cyberark.company.com \
    -UseDefaultCredentials

# Good: Use Credential
$psCredential = Get-Credential
$result = Get-CCPCredential -AppID MyApp -Safe MySafe -Object MyObject \
    -URL https://cyberark.company.com \
    -Credential $psCredential
```

--------------------------------

### Recommended Usage via Get-AIMCredential

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/start-aimclientprocess.md

Illustrates the recommended way to use the functionality by calling the public Get-AIMCredential function, which internally orchestrates the use of Invoke-AIMClient and Start-AIMClientProcess.

```powershell
# Start-AIMClientProcess is invoked internally by Invoke-AIMClient
# which is invoked by Get-AIMCredential
$cred = Get-AIMCredential -AppID MyApp -Safe MySafe -UserName testuser
```

--------------------------------

### Verify Configuration Persistence

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/set-aimconfiguration.md

Demonstrates how the configuration is automatically loaded from the AIMConfiguration.xml file when the module is imported in a new PowerShell session.

```powershell
# Run in a new PowerShell session
Import-Module CredentialRetriever

# Configuration is automatically loaded from AIMConfiguration.xml
$AIM = Get-Variable -Name AIM -Scope Script -ValueOnly
Write-Host "CLIPasswordSDK path: $($AIM.ClientPath)"
```

--------------------------------

### Configure CLIPasswordSDK Path

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Run Set-AIMConfiguration to set the path to CLIPasswordSDK.exe before using Get-AIMCredential. This is required if the SDK is not found.

```powershell
# Configure CLIPasswordSDK path first
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Then use Get-AIMCredential
$cred = Get-AIMCredential -AppID MyApp -Safe MySafe -UserName myuser
```

--------------------------------

### Manage Application Configuration with PowerShell

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/integration-patterns.md

Retrieves multiple credentials from the vault and populates an application configuration file in JSON format. Ensure the configuration path is writable.

```powershell
Import-Module CredentialRetriever

function New-ConfigurationFromVault {
    param(
        [string]$AppID,
        [string]$ConfigPath = "C:\AppConfig\settings.json"
    )

    # Retrieve multiple credentials
    $dbCred = Get-CCPCredential -AppID $AppID `
        -Safe "DatabaseAccounts" `
        -Object "PROD-Database" `
        -URL "https://cyberark.company.com"

    $apiCred = Get-CCPCredential -AppID $AppID `
        -Safe "APIAccounts" `
        -Object "ExternalAPI" `
        -URL "https://cyberark.company.com"

    # Build configuration object
    $config = @{
        Database = @{
            Username = $dbCred.UserName
            Password = $dbCred.Content
            Server = $dbCred.Address
        }
        API = @{
            Username = $apiCred.UserName
            Password = $apiCred.Content
            Endpoint = "https://api.example.com"
        }
        Environment = "Production"
        LastUpdated = (Get-Date).ToString('o')
    }

    # Save to JSON
    $config | ConvertTo-Json | Set-Content -Path $ConfigPath
    
    Write-Host "Configuration updated at $ConfigPath"
}

# Usage
New-ConfigurationFromVault -AppID "MyApp" -ConfigPath "C:\MyApp\config.json"
```

--------------------------------

### Get CCP Credential with Client Certificate

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Retrieves credentials from CCP using a client certificate for authentication. Replace 'THUMBPRINT_HERE' with your actual certificate thumbprint.

```powershell
$cert = Get-Item Cert:\CurrentUser\My\THUMBPRINT_HERE
$cred = Get-CCPCredential -AppID MyApp `
    -Safe MySafe `
    -Object MyObject `
    -URL https://cyberark.company.com `
    -Certificate $cert
```

--------------------------------

### Start-AIMClientProcess Function

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/start-aimclientprocess.md

Executes a pre-configured System.Diagnostics.Process object for a CLIPasswordSDK invocation, capturing its output and exit code. This is an internal function and direct usage is not recommended.

```APIDOC
## Start-AIMClientProcess

### Description
Internal function that executes a pre-configured `System.Diagnostics.Process` object representing a CLIPasswordSDK invocation. It captures the standard output and standard error streams, waits for process completion, and returns a result object containing the exit code and captured output.

**Note**: This is a private/internal function used only by [Invoke-AIMClient](invoke-aimclient.md). Direct usage is not recommended.

### Signature
```powershell
function Start-AIMClientProcess {
    [CmdLetBinding(SupportsShouldProcess)]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'ShouldProcess handling is in Invoke-AIMClient')]
    param(
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [System.Diagnostics.Process] $Process
    )
}
```

### Parameters
#### Path Parameters
- **Process** (System.Diagnostics.Process) - Required - A configured System.Diagnostics.Process object. Must have StartInfo.RedirectStandardOutput and StartInfo.RedirectStandardError set to $true.

### Return Type
Returns a `PSCustomObject` with the following properties:
- **ExitCode** (int) - Process exit code (0 = success, non-zero = error)
- **StdOut** (string) - Complete standard output from the process
- **StdErr** (string) - Complete standard error output from the process

### Usage Examples
#### Direct invocation (not recommended)
```powershell
# Create and configure process
$Process = New-Object System.Diagnostics.Process
$Process.StartInfo.FileName = "C:\CyberArk\CLIPasswordSDK.exe"
$Process.StartInfo.Arguments = "/p AppDescs.AppID=`"TestApp`" /p Query=`"Safe=TestSafe`" /o Password"
$Process.StartInfo.RedirectStandardOutput = $true
$Process.StartInfo.RedirectStandardError = $true
$Process.StartInfo.UseShellExecute = $false
$Process.StartInfo.CreateNoWindow = $true
$Process.StartInfo.WindowStyle = 'hidden'

# Execute and capture output
$result = Start-AIMClientProcess -Process $Process

if ($result.ExitCode -eq 0) {
    Write-Host "Success: $($result.StdOut)"
} else {
    Write-Host "Error: $($result.StdErr)"
    Write-Host "Exit Code: $($result.ExitCode)"
}
```

#### Via Invoke-AIMClient (recommended)
```powershell
# Start-AIMClientProcess is invoked internally by Invoke-AIMClient
# which is invoked by Get-AIMCredential
$cred = Get-AIMCredential -AppID MyApp -Safe MySafe -UserName testuser
```

### Error Handling
The function does not throw errors or validate the process exit code. The caller (Invoke-AIMClient) is responsible for checking the ExitCode value, parsing error messages from StdErr, and throwing appropriate errors.
```

--------------------------------

### Access Module About Topic

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/module-overview.md

Use Get-Help to access the about topic for the Credential Retriever module.

```powershell
Get-Help about_CredentialRetriever
```

--------------------------------

### Verify File Path Exists

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Before setting the ClientPath, verify that the specified file exists using Test-Path. This prevents errors related to non-existent files.

```powershell
# Verify file exists
Test-Path "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"
```

--------------------------------

### Get AIM Credential with Regular Expression Search

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Retrieves credentials using the local AIM provider and a regular expression to match the username. This allows for flexible username searching.

```powershell
$cred = Get-AIMCredential -AppID MyApp `
    -Safe MySafe `
    -UserName "svc-.*" `
    -QueryFormat regexp
```

--------------------------------

### Check AIM Configuration Before Use

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Verify if CLIPasswordSDK is configured by checking the AIM variable and its ClientPath. If not configured, run Set-AIMConfiguration.

```powershell
# Check if CLIPasswordSDK is configured
$aimConfig = Get-Variable -Name AIM -Scope Script -ErrorAction SilentlyContinue
if ($null -eq $aimConfig -or $null -eq $aimConfig.Value.ClientPath) {
    Write-Host "CLIPasswordSDK not configured. Running Set-AIMConfiguration..."
    Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"
}
```

--------------------------------

### Get CCP Credential with OS User Authentication

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Retrieves credentials from CCP using the current operating system user's credentials for authentication. This is useful in domain-joined environments.

```powershell
$cred = Get-CCPCredential -AppID MyApp `
    -Safe MySafe `
    -Object MyObject `
    -URL https://cyberark.company.com `
    -UseDefaultCredentials
```

--------------------------------

### Module Integration: Automatic Configuration Import

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/set-aimconfiguration.md

This code block shows the logic within the module that automatically imports the AIMConfiguration.xml file when the module loads, if the file exists. This ensures the CLIPasswordSDK path is available to other module functions.

```powershell
$ConfigFile = "$env:USERPROFILE\AIMConfiguration.xml"
If (Test-Path $ConfigFile) {
    $config = Import-Clixml -Path $ConfigFile
    Set-Variable -Name AIM -Value $config -Scope Script
}
```

--------------------------------

### Handle HTTP Error Response from CCP

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Catch exceptions when the CCP Web Service returns a non-2xx HTTP status code. This example specifically checks for a 404 (Not Found) error.

```powershell
try {
    $cred = Get-CCPCredential -AppID MyApp -Safe MySafe -Object NonExistent -URL https://cyberark.company.com
} catch {
    if ($_.Exception.Message -like "*404*") {
        Write-Host "Credential not found"
    }
}
```

--------------------------------

### Start-AIMClientProcess Function Signature

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/start-aimclientprocess.md

Defines the signature of the Start-AIMClientProcess function, including its parameters and cmdlet binding attributes. Supports ShouldProcess for safe execution.

```powershell
function Start-AIMClientProcess {
    [CmdLetBinding(SupportsShouldProcess)]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'ShouldProcess handling is in Invoke-AIMClient')]
    param(
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [System.Diagnostics.Process] $Process
    )
}
```

--------------------------------

### Set AIM Configuration with Valid Path

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Use Set-AIMConfiguration with a valid and existing ClientPath. This is the solution for 'Invalid File Path' errors.

```powershell
# Set with correct path
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"
```

--------------------------------

### Get Credentials from CCP Web Service

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/README.md

Retrieves credentials from the CyberArk Central Credential Provider (CCP) Web Service using the Get-CCPCredential cmdlet. Requires AppID, Safe, Object, and the CCP URL.

```powershell
$cred = Get-CCPCredential -AppID MyApp `
    -Safe MySafe `
    -Object MyObject `
    -URL https://cyberark.company.com

$password = $cred.Content
$psCredential = $cred.ToCredential()
```

--------------------------------

### SSL Certificate Validation Error

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

This error occurs when the SSL/TLS secure channel cannot be established due to certificate validation issues. For testing purposes, the -SkipCertificateCheck parameter can be used, but it is not recommended for production environments. In production, ensure the proper SSL certificate is installed on the CCP server or added to the system's trusted store.

```powershell
Error: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.
```

--------------------------------

### PSCredential Construction

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/types.md

Shows how to construct a PSCredential object using a username and a SecureString representation of the password. This is a fundamental step for creating credentials that can be used for authentication.

```powershell
New-Object System.Management.Automation.PSCredential(
    $this.UserName,           # Username (string)
    $this.ToSecureString()    # Password as SecureString
)
```

--------------------------------

### Update Existing Configuration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/set-aimconfiguration.md

Shows how to update the CLIPasswordSDK path if a configuration already exists. Running Set-AIMConfiguration again with a new path will overwrite the previous setting.

```powershell
# If a configuration already exists, running the function again updates it
Set-AIMConfiguration -ClientPath "E:\NewPath\CLIPasswordSDK.exe"
```

--------------------------------

### Retrieve Credentials Using a Pre-built Query String

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-ccpcredential.md

Retrieves credentials by providing a pre-built query string. This method allows for complex filtering and selection of credentials.

```powershell
$queryString = 'AppID=PS&Object=PSP-AccountName&Safe=PS&QueryFormat=Exact'
$cred = Get-CCPCredential -Query $queryString -URL https://cyberark.yourcompany.com
```

--------------------------------

### CLIPasswordSDK Command Structure

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-aimcredential.md

Illustrates the command structure used to interact with the CLIPasswordSDK for credential retrieval. This includes parameters for AppID, query criteria, output properties, and delimiters.

```powershell
/p AppDescs.AppID="<AppID>" /p Query="<property>=<value>;<property>=<value>;..." [additional params] /o <return-props> /d <separator>
```

--------------------------------

### Retrieve PostgreSQL Credentials and Connect

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/integration-patterns.md

Retrieves PostgreSQL credentials using Get-AIMCredential and constructs a connection string for Npgsql. Ensure the Npgsql library is available.

```powershell
$cred = Get-AIMCredential -AppID "PostgresApp" `
    -Safe "DatabaseAccounts" `
    -Database "postgres_prod" `
    -RequiredProps UserName, Address, Database

# Build connection string
$connString = "Server=$($cred.Address);Database=$($cred.Database);User Id=$($cred.UserName);Password=$($cred.Password);"
$conn = New-Object Npgsql.NpgsqlConnection($connString)
$conn.Open()
```

--------------------------------

### Import CredentialRetriever Module

Source: https://github.com/pspete/credentialretriever/blob/master/README.md

Loads the CredentialRetriever module into the current PowerShell session, making its commands available for use.

```powershell
Import-Module CredentialRetriever
```

--------------------------------

### ToCredential()

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/types.md

Converts the UserName and Password properties to a System.Management.Automation.PSCredential object.

```APIDOC
## ToCredential()

### Description
Converts the UserName and password to a `System.Management.Automation.PSCredential` object.

### Requires
UserName property must be present (include in RequiredProps or returned by CLIPasswordSDK)

### Return Type
`System.Management.Automation.PSCredential`

### Example
```powershell
$cred = Get-AIMCredential -AppID YourApp -Safe YourSafe -UserName YourUser -RequiredProps UserName
$psCredential = $cred.ToCredential()
```
```

--------------------------------

### Basic Credential Retrieval by UserName

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-aimcredential.md

Retrieves a credential using the AppID, Safe, Folder, and UserName. Displays the retrieved password.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -Folder Root `
    -UserName YourUser

Write-Host "Password: $($cred.Password)"
```

--------------------------------

### Retrieve Credentials from Local Provider

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/module-overview.md

Fetch credentials from a local provider using the CLIPasswordSDK. Configure the SDK path once using Set-AIMConfiguration before retrieving credentials.

```powershell
Import-Module CredentialRetriever

# Configure CLIPasswordSDK path (once)
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Retrieve credentials
$cred = Get-AIMCredential -AppID MyApplication \
    -Safe MySafe \
    -UserName MyUser

$password = $cred.Password
```

--------------------------------

### Set-AIMConfiguration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/set-aimconfiguration.md

Configures the CLIPasswordSDK.exe path for the CredentialRetriever module. This path is persisted to an XML file for automatic loading on module import.

```APIDOC
## Set-AIMConfiguration

### Description

Configures the CLIPasswordSDK.exe utility path within the module's script scope. This setting is saved to `AIMConfiguration.xml` in the user's home directory, enabling automatic use on subsequent module imports. This function should be executed before using `Get-AIMCredential` if the CLIPasswordSDK path is not already set.

### Method

PowerShell Function

### Parameters

#### Parameters

- **ClientPath** (string) - Optional - Full path to the CLIPasswordSDK.exe utility. This path must point to an existing file and is validated using `Test-Path`.

### Return Type

Nothing. The function updates the script-scoped `$AIM` variable and saves it to the configuration file.

### Usage Examples

#### Set CLIPasswordSDK path

```powershell
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Verify the configuration was set
Get-Variable -Name AIM -Scope Script | Select-Object -ExpandProperty Value
```

#### Use with WhatIf

```powershell
# Preview what the configuration would do (note: not fully implemented in function)
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe" -WhatIf
```

### Error Handling

Throws an error if:
- `ClientPath` does not point to an existing file (ValidateScript failure).
- `ClientPath` is null or empty (ValidateNotNullOrEmpty failure).
```

--------------------------------

### Credential Query using Pre-Built Query String

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Utilizes the 'Query' parameter to pass a pre-constructed query string. Note that 'AppID' must still be provided separately.

```powershell
$queryString = 'AppID=PS&Object=PSP-AccountName&Safe=PS&QueryFormat=Exact'
$cred = Get-CCPCredential -Query $queryString -URL https://cyberark.company.com
```

--------------------------------

### Configure CLIPasswordSDK Path with Set-AIMConfiguration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/configuration.md

Use this function to set the full path to the CLIPasswordSDK.exe. This is essential for the Get-AIMCredential function to operate correctly. Ensure the specified path points to an existing file.

```powershell
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"
```

--------------------------------

### Simple Object-Based Credential Query

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Constructs a basic query to retrieve credentials using object name. Ensure the URL is correctly formatted.

```powershell
$cred = Get-CCPCredential -AppID PSScript `
    -Safe PSAccounts `
    -Object PSPlatform-AccountName `
    -URL https://cyberark.company.com

# Results in URL:
# https://cyberark.company.com/AIMWebService/api/Accounts?AppID=PSScript&Safe=PSAccounts&Object=PSPlatform-AccountName
```

--------------------------------

### Persist CLIPasswordSDK Configuration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Call Set-AIMConfiguration once to persist the CLIPasswordSDK path. The configuration is automatically loaded in future sessions.

```powershell
# Call Set-AIMConfiguration once to persist configuration
Set-AIMConfiguration -ClientPath "D:\CyberArk\CLIPasswordSDK\CLIPasswordSDK.exe"

# Configuration is loaded automatically on module import in future sessions
```

--------------------------------

### CLIPasswordSDK Command Structure

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

This is the general structure of a CLIPasswordSDK command that Get-AIMCredential builds. It includes parameters for application ID, query, query format, required properties, reason, connection parameters, output properties, and delimiter.

```powershell
GetPassword /p AppDescs.AppID="<AppID>" [/p Query="<QueryString>"] [/p QueryFormat="<Format>"] [/p RequiredProps="<Props>"] [/p Reason="<Reason>"] [/p ConnectionParms.Port=<Port>] [/p ConnectionParms.Timeout=<Timeout>] /o <OutputProperties> /d <Separator>
```

--------------------------------

### Adjust Connection Timeout and Verify Service

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/errors.md

Increase the timeout for Get-AIMCredential if the Credential Provider does not respond in time. Verify that the CLIPasswordSDK service is running.

```powershell
# Increase timeout
$cred = Get-AIMCredential -AppID MyApp -Safe MySafe -UserName myuser -Timeout 60

# Verify Credential Provider is running
Get-Service CLIPasswordSDK
```

--------------------------------

### Using connection parameters

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-aimcredential.md

Retrieves a credential specifying connection parameters like port and timeout.

```APIDOC
## Get-AIMCredential - With Connection Parameters

### Description
Retrieves a credential while specifying connection-related parameters such as port number and timeout duration.

### Method
PowerShell Cmdlet

### Parameters
- **AppID** (string) - Required - The ID of the application.
- **Safe** (string) - Required - The name of the safe.
- **UserName** (string) - Required - The username for the credential.
- **Port** (int) - Optional - The port number for the connection.
- **Timeout** (int) - Optional - The timeout duration in seconds for the connection.

### Request Example
```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -UserName YourUser `
    -Port 5084 `
    -Timeout 30
```
```

--------------------------------

### Credential Query with Connection Timeout and Reason

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Includes optional parameters for connection timeout and a reason for retrieval. The 'Reason' is logged in the audit trail.

```powershell
$cred = Get-CCPCredential -AppID PSScript `
    -Safe PSAccounts `
    -Object PSPlatform-AccountName `
    -ConnectionTimeout 30 `
    -Reason "Automated deployment script" `
    -URL https://cyberark.company.com

# Results in URL:
# https://cyberark.company.com/AIMWebService/api/Accounts?AppID=PSScript&Safe=PSAccounts&Object=PSPlatform-AccountName&ConnectionTimeout=30&Reason=Automated%20deployment%20script
```

--------------------------------

### Efficiently Collect Credentials Using Batch Operations

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Collect multiple credentials in a more efficient manner by collecting them into an array, minimizing individual function calls compared to separate retrievals.

```powershell
# Less efficient: Multiple calls
$cred1 = Get-AIMCredential -AppID App1 -Safe Safe1 -UserName user1
$cred2 = Get-AIMCredential -AppID App2 -Safe Safe2 -UserName user2

# More efficient: Collect credentials
$creds = @(
    $cred1, 
    $cred2
)
```

--------------------------------

### Retrieve Account with Audit Trail using Get-AIMCredential

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Use Get-AIMCredential to retrieve credentials while providing a reason for audit trail purposes. Requires the application ID, safe, object name, and reason.

```powershell
$cred = Get-AIMCredential -AppID MyApp `
    -Safe MySafe `
    -Object MyObject `
    -Reason "Scheduled backup job execution"
```

--------------------------------

### Set-AIMConfiguration

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/README.md

Configures the CLIPasswordSDK path for the module. This function allows you to specify the location of the SDK used for credential management.

```APIDOC
## Set-AIMConfiguration

### Description
Configures the CLIPasswordSDK path for the module. This function allows you to specify the location of the SDK used for credential management.

### Method
Invoke-Command (PowerShell cmdlet)

### Endpoint
N/A (Local PowerShell function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```powershell
Set-AIMConfiguration -CLIPasswordSDKPath "C:\Program Files\CyberArk\Password SDK\clipasswordsdk.exe"
```

### Response
#### Success Response
- **Status** (string) - Indicates the success or failure of the configuration update.

#### Response Example
```json
{
  "Status": "Success"
}
```
```

--------------------------------

### Using Regular Expression Search for Credentials

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-aimcredential.md

Retrieves credentials by using a regular expression pattern for the UserName. This allows for flexible searching of usernames.

```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -UserName "svc.*" `
    -QueryFormat regexp
```

--------------------------------

### Basic credential retrieval by UserName

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-aimcredential.md

Retrieves a credential using the AppID, Safe, Folder, and UserName.

```APIDOC
## Get-AIMCredential - Basic Retrieval

### Description
Retrieves a credential by specifying the application ID, safe name, folder, and username.

### Method
PowerShell Cmdlet

### Parameters
- **AppID** (string) - Required - The ID of the application.
- **Safe** (string) - Required - The name of the safe.
- **Folder** (string) - Required - The name of the folder within the safe.
- **UserName** (string) - Required - The username for the credential.

### Response
#### Success Response
- **Password** (string) - The retrieved password.

### Request Example
```powershell
$cred = Get-AIMCredential -AppID YourApp `
    -Safe YourSafe `
    -Folder Root `
    -UserName YourUser

Write-Host "Password: $($cred.Password)"
```
```

--------------------------------

### Retrieve Windows Account by Username with Get-AIMCredential

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/query-reference.md

Use Get-AIMCredential to retrieve Windows account credentials by specifying a username. Requires the application ID, safe, and username.

```powershell
$cred = Get-AIMCredential -AppID WindowsApp `
    -Safe WindowsAccounts `
    -UserName svc-application
```

--------------------------------

### Convert Password to SecureString

Source: https://github.com/pspete/credentialretriever/blob/master/_autodocs/api-reference/get-ccpcredential.md

Retrieves credentials and converts the password to a SecureString object. It also demonstrates how to convert the SecureString back to a plain text string for specific use cases, though this should be done with caution.

```powershell
$cred = Get-CCPCredential -AppID PS `
    -Safe PS `
    -Object PSP-AccountName `
    -URL https://cyberark.yourcompany.com

$securePassword = $cred.ToSecureString()
$plainPassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto(
    [System.Runtime.InteropServices.Marshal]::SecureStringToCoTaskMemUnicode($securePassword)
)
```