How to Use PowerShell with SharePoint Essentials Toolkit

Last updated: 2026-10-16

Run SharePoint Essentials Toolkit from PowerShell or the command line: install the Cognillo.SPE module, preview copies, copy sites and lists, run link reports and other tasks from templates, and schedule jobs.

Overview

SharePoint Essentials Toolkit ships with a PowerShell module, Cognillo.SPE, that lets you run the toolkit from PowerShell and the command line instead of clicking through the app. Use it to repeat a task, run it for many sites at once from a spreadsheet, or run it on a schedule.

There are two ways to run jobs from a script:

• PowerShell commands such as Copy-SPEList and Copy-SPESite. Best for interactive use and most scripts. They return a result object you can inspect, filter or export.
• A job spec file run from the command line (SharePoint Essentials Toolkit.exe --run-spec). Best for scheduled tasks and CI/CD. The PowerShell commands write this file for you.

Every job you run from a script:

• appears on the app's History page with its full report, exactly like a job started from the app;
• can be previewed first with -WhatIf, which reads both sites and shows what would be copied without copying anything;
• follows the same license rules as jobs you run in the app.

Copies are described entirely in the command, which makes them the most flexible to script. Every other task (link reports, inventories, permission reports and so on) is set up once in the app, saved as a job template, and then run from a script. See Run link reports and other tasks below.

Before you start

Install the module

The module is a folder named Cognillo.SPE containing Cognillo.SPE.psd1 and Cognillo.SPE.psm1.

Option A: install for your user (recommended)

# Windows PowerShell 5.1
$modules = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'WindowsPowerShell\Modules'
# PowerShell 7: use 'PowerShell\Modules' instead of 'WindowsPowerShell\Modules'

New-Item -ItemType Directory -Force $modules | Out-Null
Copy-Item -Recurse -Force '.\Cognillo.SPE' $modules
Get-ChildItem (Join-Path $modules 'Cognillo.SPE') | Unblock-File

Option B: load it from any folder

Import-Module 'C:\Tools\Cognillo.SPE'

Check that it works:

Get-Command -Module Cognillo.SPE
Get-SPEExecutable   # shows where SharePoint Essentials Toolkit.exe was found

Quick start: copy lists

First preview the copy. -WhatIf signs in, reads both sites and lists exactly what would be copied. Nothing is changed.

Copy-SPEList -SourceSite 'https://contoso.sharepoint.com/sites/HR' `
    -DestinationSite 'https://contoso.sharepoint.com/sites/HR-Archive' `
    -List 'Documents', 'Policies' -WhatIf

Then run it. Remove -WhatIf. Progress is shown in the console; press Ctrl+C to cancel safely.

$result = Copy-SPEList -SourceSite 'https://contoso.sharepoint.com/sites/HR' `
    -DestinationSite 'https://contoso.sharepoint.com/sites/HR-Archive' `
    -List 'Documents', 'Policies'

Then check the result:

$result | Format-List *
$result.Status             # Completed, CompletedWithWarnings, Error, Cancelled ...
$result.ItemsCompleted
$result.Messages           # errors and warnings found while preparing the job

The full report (every item copied, skipped or failed) is on the app's History page.

Copying lists and libraries

Copy-SPEList copies the lists and libraries you name. Useful options:

# Ignore named lists that don't exist on the source
Copy-SPEList -SourceSite $src -DestinationSite $dst -List 'Documents', 'Contracts' -IgnoreMissingLists

You can also pipe a list of targets, so the same lists are copied to several sites:

Import-Csv .\targets.csv |
ForEach-Object { [pscustomobject]@{ SourceSite = $src; DestinationSite = $_ } } |
Copy-SPEList -List 'Price Lists'

Copying sites

Copy-SPESite copies a whole site into an existing target site. It asks for confirmation before running; add -Confirm:$false in unattended scripts.

Copy-SPESite -SourceSite $src -DestinationSite $dst -Confirm:$false

Bulk copies from a CSV file

Put one copy per row in a CSV file and pipe it. Rows with the same source and target are combined automatically, so several rows for one site become a single copy.

Import-Csv .\copies.csv | Copy-SPEList

Run link reports and other tasks

Any task you can run in the app can also run from a script, not only copies: links reports, inventories, permissions and sharing reports, storage and activity reports, Content Search and more. You set the task up once in the app, choose the options and report delivery (email or SharePoint library), and save it as a job template. A script then runs that template as saved, or against other sites.

Save the task as a template

1. In the app, set up the task as usual — for example, a links report on one site that looks for broken links.
2. Choose how the report is delivered, if at all: by email or to a SharePoint library. Scripted runs deliver the report the same way.
3. Save it as a job template, for example Broken links. On the Job Templates page you can copy a ready-made PowerShell command for it.

Run it from PowerShell

# Run the template exactly as saved
Invoke-SPEJobTemplate -Name 'Broken links'

# Run it against a different site. The template's options are used; its sites are replaced.
Invoke-SPEJobTemplate -Name 'Broken links' -Url 'https://contoso.sharepoint.com/sites/Intranet'

The report itself (every link found, its status and where it is) is on the app's History page, and is delivered by email or to SharePoint if the template is set up to do so.

One report per site from a CSV file

Each site is run separately, so every site gets its own report:

$results = Import-Csv .\sites.csv | Invoke-SPEJobTemplate -Name 'Broken links'
$results | Where-Object ExitCode -ne 0   # the sites that need a look

Run a task again from History

Every task in History has an ID. Select the task on the History page and choose PowerShell › Copy command or Create script file…, or run it with the module:

Invoke-SPEJob -Id '6f1b8e0a-3c1d-4c35-9a41-2f8f0c7d9b11'

Collect user activity

If User Activity is set up in the app, collect the latest activity from the Microsoft 365 audit log before running an activity report:

Sync-SPEUserActivity
Invoke-SPEJobTemplate -Name 'Inactive sites'

For copies, prefer Copy-SPEList and Copy-SPESite: they work without a template, can preview with -WhatIf, and return detailed counts. For all other tasks use Invoke-SPEJobTemplate and Invoke-SPEJob: they return the task's status and exit code, and the details are in History.

Check the results and exit codes

Every copy command returns one result per job. Useful properties include Status (Completed, CompletedWithWarnings, CompletedWithErrors, Error, Cancelled — or Planned for -WhatIf), JobId, JobName and JobType (identify the job in History), list and item counts, Errors and Warnings, Plan (one entry per source list, including whether the target list already exists) and Messages (problems found while preparing the job).

After each run, $LASTEXITCODE holds the job's exit code:

Scheduling

To run a job on a schedule, write a small .ps1 script (for example the weekly reports script from the full guide), then register it with Windows Task Scheduler with New-ScheduledTaskAction. The same approach works for reports and copies. The result file and exit codes make it easy to check whether a scheduled run succeeded. See the full guide below for worked examples.

Troubleshooting

Full guide

The complete PowerShell Scripting Guide (PDF) covers everything above in more depth, plus advanced topics: copy settings and templates, user mappings between tenants, the job spec file format, the full command line and PowerShell command reference, and a troubleshooting and FAQ section.