snipe-it-ps

A PowerShell module for the Snipe-IT Asset Management REST API.

Requirements

• PowerShell 5.1 or later (Windows PowerShell and PowerShell Core/7+)
• A Snipe-IT instance with API access
• A Snipe-IT API token (generated in Admin → API → Generate Token)

Installation

From the repository

git clone https://github.com/djeborn/snipe-it-ps.git
Import-Module ./snipe-it-ps/SnipeIT/SnipeIT.psd1

Manual (copy folder)

Copy the SnipeIT folder to one of your $env:PSModulePath directories, then:

Import-Module SnipeIT

Quick Start

# 1. Connect to your Snipe-IT instance
Connect-SnipeIT -Url 'https://inventory.example.com' -Token 'your-api-token'

# Or connect using a SecureString token (recommended)
$secureToken = Read-Host -AsSecureString 'API Token'
Connect-SnipeIT -Url 'https://inventory.example.com' -SecureToken $secureToken

# 2. List all assets
Get-SnipeITAsset -All

# 3. Get a specific asset by ID
Get-SnipeITAsset -Id 42

# 4. Get an asset by asset tag
Get-SnipeITAsset -AssetTag 'LAPTOP-001'

# 5. Create a new asset
New-SnipeITAsset -ModelId 3 -StatusId 1 -AssetTag 'LAPTOP-999' -Name 'Alice Laptop'

# 6. Update an asset
Set-SnipeITAsset -Id 42 -Name 'Updated Name' -Notes 'Replaced keyboard'

# 7. Check out an asset to a user
Invoke-SnipeITAssetCheckout -Id 42 -AssignedUser 7

# 8. Check in an asset
Invoke-SnipeITAssetCheckin -Id 42

# 9. Delete an asset
Remove-SnipeITAsset -Id 42

# 10. Disconnect
Disconnect-SnipeIT

Available Commands

Connection

Command	Description
Connect-SnipeIT	Store base URL and API token for the session
Disconnect-SnipeIT	Clear stored credentials

Assets (Hardware)

Command	Description
Get-SnipeITAsset	Get asset(s) — by ID, asset tag, serial, or list
New-SnipeITAsset	Create a new asset
Set-SnipeITAsset	Update an existing asset
Remove-SnipeITAsset	Delete an asset
Invoke-SnipeITAssetCheckout	Check out an asset to a user/location/asset
Invoke-SnipeITAssetCheckin	Check in an asset
Invoke-SnipeITAssetAudit	Record an asset audit
Get-SnipeITAssetFile	List files attached to an asset
Add-SnipeITAssetFile	Upload a file attachment to an asset
Remove-SnipeITAssetFile	Delete a file attached to an asset

Accessories

Command	Description
Get-SnipeITAccessory	Get accessory/accessories
New-SnipeITAccessory	Create an accessory
Set-SnipeITAccessory	Update an accessory
Remove-SnipeITAccessory	Delete an accessory
Invoke-SnipeITAccessoryCheckout	Check out an accessory to a user
Invoke-SnipeITAccessoryCheckin	Check in an accessory

Categories, Companies, Components, Consumables

Each resource supports full CRUD: Get-, New-, Set-, Remove-.

Resource	Noun
Categories	SnipeITCategory
Companies	SnipeITCompany
Components	SnipeITComponent
Consumables	SnipeITConsumable

Departments, Groups, Licenses, Locations

Resource	Noun	Additional Commands
Departments	SnipeITDepartment
Groups	SnipeITGroup
Licenses	SnipeITLicense	Get/Set-SnipeITLicenseSeat, Invoke-SnipeITLicenseSeatCheckout, Invoke-SnipeITLicenseSeatCheckin
Locations	SnipeITLocation

Maintenance, Manufacturers, Models, Status Labels

Resource	Noun
Maintenance records	SnipeITMaintenance
Manufacturers	SnipeITManufacturer
Asset models	SnipeITModel (includes Get/Add/Remove-SnipeITModelFile)
Status labels	SnipeITStatusLabel

Custom Fields & Fieldsets, Suppliers, Users

Resource	Commands
Custom fields	Get/New/Set/Remove-SnipeITCustomField
Fieldsets	Get/New/Set/Remove-SnipeITFieldset
Suppliers	Get/New/Set/Remove-SnipeITSupplier (full CRUD)
Users	Get/New/Set/Remove-SnipeITUser, Get-SnipeITUserApiToken, New-SnipeITUserApiToken, Remove-SnipeITUserApiToken

Reports & Analytics

Command	Description
Get-SnipeITActivity	Retrieve activity log entries (supports -All pagination)
Get-SnipeITAssetMaintenanceReport	Asset maintenance history and schedules
Get-SnipeITDepreciationReport	Asset depreciation and book values
Get-SnipeITLicenseReport	License compliance and seat allocation
Get-SnipeITUnacceptedAssetReport	Assets with unaccepted EULAs

Settings & Configuration

Command	Description
Get-SnipeITBackup	List available backup files
Save-SnipeITBackup	Download a backup file to the local file system
Get-SnipeITSettings	Retrieve general instance settings and configuration
Get-SnipeITLdapSettings	Retrieve LDAP/AD integration settings
Test-SnipeITLdapConnection	Test LDAP/AD connection and authentication

Pagination

List commands default to 50 results. Use -Limit and -Offset for manual pagination, or pass -All to automatically retrieve every page:

# Get everything
$assets = Get-SnipeITAsset -All

# Manual pagination
$page1 = Get-SnipeITAsset -Limit 100 -Offset 0
$page2 = Get-SnipeITAsset -Limit 100 -Offset 100

Filtering & Sorting

# Search by keyword
Get-SnipeITAsset -Search 'MacBook'

# Filter assets by model, location, status
Get-SnipeITAsset -ModelId 5 -LocationId 2 -StatusId 1

# Sort results
Get-SnipeITAsset -Sort 'name' -Order 'asc'

File Attachments

Upload and manage file attachments for assets and models:

# Upload an invoice PDF to an asset
Add-SnipeITAssetFile -AssetId 42 -FilePath 'C:\invoices\invoice.pdf' -Notes 'Purchase invoice'

# List files attached to an asset
Get-SnipeITAssetFile -AssetId 42

# Delete a file from an asset
Remove-SnipeITAssetFile -AssetId 42 -FileId 7

# Upload a datasheet to an asset model
Add-SnipeITModelFile -ModelId 5 -FilePath 'C:\specs\datasheet.pdf' -Notes 'Vendor datasheet'

Backup Management

# List available backup files
Get-SnipeITBackup

# Download a backup to the local file system
Save-SnipeITBackup -FileName 'snipeit-backup-2024-01-15.zip' -OutFile 'C:\Backups\snipeit.zip'

# Download the most recent backup automatically
$latest = Get-SnipeITBackup | Select-Object -First 1
Save-SnipeITBackup -FileName $latest.filename -OutFile "C:\Backups\$($latest.filename)"

License Seat Management

Manage software license seat assignments:

# Get all seats for a license
Get-SnipeITLicenseSeat -LicenseId 10

# Check out a license seat to a user
Invoke-SnipeITLicenseSeatCheckout -LicenseId 10 -SeatId 3 -AssignedTo 5

# Check out a license seat to an asset
Invoke-SnipeITLicenseSeatCheckout -LicenseId 10 -SeatId 3 -AssetId 100

# Check in a license seat (make it available)
Invoke-SnipeITLicenseSeatCheckin -LicenseId 10 -SeatId 3

# Update a license seat assignment directly
Set-SnipeITLicenseSeat -LicenseId 10 -SeatId 3 -AssignedTo 7 -Note 'Reassigned to new employee'

Reports & Analytics

Generate comprehensive reports for asset management:

# Get activity log entries
Get-SnipeITActivity -All

# Filter activity by action type
Get-SnipeITActivity -ActionType 'checkout' -Limit 100

# Get asset maintenance report
Get-SnipeITAssetMaintenanceReport -All

# Get depreciation report for financial analysis
Get-SnipeITDepreciationReport -All -Sort 'purchase_cost'

# Get license compliance report
Get-SnipeITLicenseReport -All

# Get assets with unaccepted EULAs
Get-SnipeITUnacceptedAssetReport

User API Token Management

Manage API tokens for automated integrations:

# List all API tokens for a user
Get-SnipeITUserApiToken -UserId 10

# Generate a new API token for a user
New-SnipeITUserApiToken -UserId 10 -Name 'Automation Script Token'

# Revoke an API token
Remove-SnipeITUserApiToken -UserId 10 -TokenId 5

Settings & Configuration

Retrieve and test instance settings:

# Get general instance settings
$settings = Get-SnipeITSettings
$settings.site_name

# Get LDAP/AD configuration
Get-SnipeITLdapSettings

# Test LDAP connection
Test-SnipeITLdapConnection

# Test LDAP authentication with specific credentials
Test-SnipeITLdapConnection -Username 'testuser' -Password 'password123'

Supplier Management

Full CRUD operations for suppliers:

# List all suppliers
Get-SnipeITSupplier -All

# Get a specific supplier
Get-SnipeITSupplier -Id 5

# Create a new supplier
New-SnipeITSupplier -Name 'Acme Corp' -Email 'sales@acme.com' -Phone '555-0100'

# Update a supplier
Set-SnipeITSupplier -Id 5 -Email 'newsales@acme.com'

# Delete a supplier
Remove-SnipeITSupplier -Id 5

Custom Fields

Pass custom field database column names in the -CustomFields hashtable:

New-SnipeITAsset -ModelId 1 -StatusId 1 -CustomFields @{
    '_snipeit_imei_1' = '352099001761481'
}

Pipeline Support

Remove-* and pipeline-friendly commands accept values from the pipeline:

# Delete multiple assets from the pipeline
Get-SnipeITAsset -Search 'old' | Remove-SnipeITAsset -Confirm:$false

# Pipe IDs directly
42, 43, 44 | Remove-SnipeITAsset

ShouldProcess / WhatIf / Confirm

All write commands support -WhatIf and -Confirm:

Remove-SnipeITAsset -Id 42 -WhatIf
Set-SnipeITAsset -Id 42 -Name 'New Name' -Confirm:$false

Help

Every function has full comment-based help:

Get-Help Connect-SnipeIT -Full
Get-Help Get-SnipeITAsset -Examples

Running Tests

The module ships with Pester 5 unit tests:

# Install Pester if not already installed
Install-Module Pester -Force

# Run all tests
Invoke-Pester ./Tests

PowerShell / Encoding

This module supports PowerShell 5.1 (Windows PowerShell) and PowerShell 7+. When working with accented or special characters (é, ë, ç, Å, ö, …) on either version, always pass an explicit encoding parameter so characters are not silently corrupted.

• When writing or reading files in scripts, explicitly set UTF-8 encoding, e.g. Set-Content -Path .\file.txt -Value $text -Encoding utf8 or Out-File -FilePath .\file.txt -InputObject $text -Encoding utf8.
• PS 5.1 note: -Encoding utf8 writes a UTF-8 BOM; this is harmless — the BOM is stripped on read-back and the text round-trips correctly.
• If you need the Snipe-IT API docs for PowerShell usage, see: https://snipe-it.readme.io/reference/powershell

Quick checks and fixes:

• Check PowerShell version: $PSVersionTable.PSVersion
• Check console encoding: [Console]::OutputEncoding
• Force UTF-8 for the current session: [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Example write/read test (see tools/test-accent.ps1 included in this repo):

# PS 7+
pwsh -NoProfile -ExecutionPolicy Bypass ./tools/test-accent.ps1

# PS 5.1 (Windows PowerShell)
powershell -NoProfile -ExecutionPolicy Bypass ./tools/test-accent.ps1

Security Best Practices

API Token Security

IMPORTANT: API tokens are stored in plain-text in memory for the duration of the PowerShell session. Consider the following security practices:

• Use Connect-SnipeIT -SecureToken with a SecureString token instead of plain-text -Token parameter when possible
• Always use Disconnect-SnipeIT when finished to clear credentials from memory
• Never commit API tokens to source control or share them in logs/scripts
• Use credential storage solutions (Windows Credential Manager, Azure Key Vault, etc.) for production use
• Rotate API tokens regularly and revoke unused tokens in Snipe-IT admin panel

Image Upload Security

Image uploads are validated for security:

• Maximum file size: 10 MB
• Allowed extensions: .jpg, .jpeg, .png, .gif, .bmp, .svg, .webp
• MIME type validation ensures only image types are accepted
• File path validation prevents directory traversal attacks

TLS/SSL Security

The module automatically enables TLS 1.2 for API connections while preserving any existing TLS protocols (such as TLS 1.3). The original security protocol settings are restored after each API call to avoid affecting other modules or scripts in your session.

Rate Limiting

Use the throttling features to avoid overwhelming your Snipe-IT server:

# Connect with throttling enabled
Connect-SnipeIT -Url 'https://inventory.example.com' -Token 'your-api-token' `
    -ThrottleLimit 60 -ThrottlePeriod 60000 -ThrottleMode 'Burst'

Throttle modes:

• Burst: Allows up to N requests in the period, then waits
• Constant: Evenly distributes requests throughout the period
• Adaptive: Dynamically adjusts based on current usage

API Reference

• Snipe-IT API Documentation: https://snipe-it.readme.io/reference/api-overview
• Snipe-IT PowerShell API Reference: https://snipe-it.readme.io/reference/powershell
• OpenAPI Specification: included in snipe-it-rest-api.json

License

AGPL-3.0