Deployment Packages PowerShell Module

AthenaDeploymentPackages is a dedicated PowerShell module that scripts the entire Athena deployment-package workflow end to end: sign in, build ordered steps, create/update/delete packages, upload/list/remove package files, rebuild the bundle, deploy to agents, tags or collections, and poll an execution until it finishes. It wraps the same api/deployment-packages endpoints used by the console, so anything you can do in the Deployments UI can be automated. For the field-by-field step reference (step types, OS conditions, run-as, exit codes) see Deployment Package Steps.

Requirements & roles#

• PowerShell 7 or newer. The module relies on PowerShell 7 features (-SkipCertificateCheck for a self-signed server certificate and -Form for multipart file upload).
• Network reach to the Athena web port (default 8443; see Network Ports).
• Roles. Creating, updating, deleting, uploading/removing files, building, and deploying require the Admin role. Listing, reading a package, and reading an execution require the Operator role (Operators and Admins). See Roles & Permissions.

Importing the module#

Import the module manifest, then sign in with Connect-AthenaServer. The session (base URL and token) is stored in the module and reused automatically by every other cmdlet, so you only authenticate once per shell.

Import-Module ./AthenaDeploymentPackages.psd1 -Force

# Sign in — the session is cached and reused by the other cmdlets
Connect-AthenaServer -BaseUrl https://athena.example.com:8443 -Username admin -Password '<your-password>'

# …or prompt for a credential instead of a plaintext password
Connect-AthenaServer -BaseUrl https://athena.example.com:8443 -Credential (Get-Credential)

Connect-AthenaServer defaults -BaseUrl to https://localhost:8443 and trusts a self-signed certificate by default (-SkipCertificateCheck $true). Against a server with a trusted certificate, pass -SkipCertificateCheck $false. Add -PassThru to return the session object if you want to capture it and pass it explicitly with the common -Session parameter.

Cmdlet reference#

Every cmdlet unwraps the standard response envelope and returns the payload directly, and throws a terminating error if the server reports failure. Mutating cmdlets that delete data (Remove-*) support -WhatIf and -Confirm.

Building steps#

New-AthenaDeploymentStep builds a single step for a package. It accepts friendly names for -Type, -RunAs, and -OsCondition and translates them to the values the API expects, so you don't have to remember any codes. Pass an array of the objects it returns to New-AthenaDeploymentPackage -Steps or Set-AthenaDeploymentPackage -Steps.

Files & rebuilding#

Steps such as InstallApplication and CopyFiles reference a file that must first be uploaded to the package. Add-AthenaDeploymentPackageFile -Id <pkg> -Path <file> uploads a file and rebuilds the bundle in one call; Remove-AthenaDeploymentPackageFile removes one and rebuilds. Because upload and remove both rebuild automatically, you rarely need Invoke-AthenaDeploymentPackageBuild — it is there to force a rebuild on demand. A single file upload is capped at 1 GB.

Deploying & targeting#

Start-AthenaDeploymentPackageDeploy creates a deployment execution and — unless you schedule it — starts it right away. You must give the execution a -Name and at least one target; the targeting parameters can be combined:

Monitoring executions#

Get-AthenaDeploymentExecution -ExecutionId <id> returns the execution's rollup counters (totalAgents, completedAgents, failedAgents, runningAgents, progressPercent), the current step, and a per-agent breakdown with per-step results. Wait-AthenaDeploymentExecution polls it for you until it reaches a terminal state, with tunable -TimeoutSeconds (default 300) and -PollSeconds (default 5). The status is one of:

End-to-end example#

A complete create → upload → deploy → wait run that installs 7-Zip on every workstation-tagged agent and then refreshes inventory:

Import-Module ./AthenaDeploymentPackages.psd1 -Force
Connect-AthenaServer -BaseUrl https://athena.example.com:8443 -Username admin -Password '<your-password>'

# 1. Build the ordered steps (friendly enum names — no codes to remember)
$steps = @(
  New-AthenaDeploymentStep -Name 'Install 7-Zip' -Order 1 -Type InstallApplication `
    -FileName '7z2408-x64.msi' -Arguments '/qn /norestart' `
    -SuccessExitCodes '0,3010' -OsCondition Windows11 -TimeoutSeconds 600
  New-AthenaDeploymentStep -Name 'Refresh inventory' -Order 2 -Type TriggerInventory
)

# 2. Create the package, then upload the file the step references
#    (uploading rebuilds the bundle automatically)
$pkg = New-AthenaDeploymentPackage -Name '7-Zip 24.08' -FolderName '7zip-2408' -Steps $steps
Add-AthenaDeploymentPackageFile -Id $pkg.id -Path '.\7z2408-x64.msi'

# 3. Deploy to a tag now, then wait for the result
$exec = Start-AthenaDeploymentPackageDeploy -Id $pkg.id -Name '7-Zip rollout' -TargetTag 'workstation'
$result = Wait-AthenaDeploymentExecution -ExecutionId $exec.id -Verbose

# 4. Inspect the per-agent, per-step outcome
$result.agentResults.stepResults | Select-Object stepName, exitCode, output, errorOutput