Get-Team and New-Team: list and create Microsoft Teams teams with PowerShell

After Connect-MicrosoftTeams, list teams with Get-Team and create one with New-Team:

Get-Team -DisplayName "Marketing"                     # filter by name
Get-Team -User anna@contoso.com                       # teams a user belongs to
Get-Team -Archived $true                              # archived teams

$team = New-Team -DisplayName "Project Phoenix" -Description "Launch planning" -Visibility Private -Owner anna@contoso.com
Add-TeamUser -GroupId $team.GroupId -User bob@contoso.com
Add-TeamUser -GroupId $team.GroupId -User carol@contoso.com -Role Owner

New-Team returns an object with the GroupId of the new Microsoft 365 group; the other team cmdlets identify the team by that ID.

Allowed values

-Visibility and -Template of New-Team, and -Role of Add-TeamUser, accept a fixed set of values. Read from MicrosoftTeams 8.0.0 offline:

Import-Module MicrosoftTeams
function Show-Set($cmd, $param) {
  $set = (Get-Command $cmd).Parameters[$param].Attributes |
    Where-Object { $_ -is [System.Management.Automation.ValidateSetAttribute] }
  '{0} -{1}: {2}' -f $cmd, $param, ($set.ValidValues -join ', ')
}
Show-Set New-Team Visibility
Show-Set New-Team Template
Show-Set Add-TeamUser Role

New-Team -Visibility: Public, Private, HiddenMembership
New-Team -Template: EDU_Class, EDU_PLC
Add-TeamUser -Role: Owner, Member

Get-Team -Visibility takes the same words but has no validation set in 8.0.0, so a typo returns no teams instead of an error.

Useful New-Team parameters

Get-Team filters

Get-Team has seven filter parameters in MicrosoftTeams 8.0.0. Without any of them it returns every team in the tenant, which can take a long time in a large organization:

Requirements

Install the MicrosoftTeams module, then run Connect-MicrosoftTeams in the same session; both Windows PowerShell 5.1 and PowerShell 7 work. Listing and creating teams for other people needs the Teams Administrator or Global Administrator role. A normal user can create teams for themselves when the tenant allows group creation. Before you connect, Get-Team fails with Session is not established; see Connect-MicrosoftTeams for interactive, device-code and certificate sign-in.

Pitfalls

• Wrong visibility value. New-Team -Visibility Hidden is rejected by the validation set before anything is sent; the exact message and fix are on New-Team Visibility ValidateSet.
• Duplicate names. Team display names do not have to be unique, so Get-Team -DisplayName can return several teams. Store and reuse the GroupId in scripts.
• Owner leaves. A team should keep at least two owners; add a second one with Add-TeamUser -Role Owner right after creation, as in the first example.
• Archiving versus deleting. Set-TeamArchivedState makes a team read-only and keeps it, while Remove-Team deletes the underlying Microsoft 365 group with its mailbox and SharePoint site.

FAQ