PowerShell Module

The Athena PowerShell module wraps the same JWT-authenticated REST API the console uses, so you can automate your fleet from scripts. Connect once with Connect-Athena, then drive agents, deployments, commands, collections, packages, scheduled jobs, users, PKI and more with over a hundred cmdlets.

Import the module#

Copy the module folder onto a management host and import it. The manifest declares a minimum of PowerShell 5.1, so no extra runtime is required on a current Windows box.

# Import by path…
Import-Module .\Athena\Athena.psd1

# …or by name, once the folder is on $env:PSModulePath
Import-Module Athena

# Confirm it loaded and list the cmdlets
Get-Command -Module Athena

Connect & authenticate#

Connect-Athena establishes an authenticated session and stores it in a module-level variable that every other cmdlet reuses. Connections are HTTPS only; pass the bare hostname (no protocol) and, if needed, a port. The default port is 8443. The authenticating provider — Local, Ldap or Keycloak — is surfaced on the returned session (its AuthProvider) and in the “Connected” message.

Supported providers#

Connect-Athena supports two login flows, which map to the three providers the server accepts:

With the username/password flow you do not choose Local versus Ldap yourself — you supply a credential (or accept the prompt) and the server authenticates it against the appropriate provider, then reports which one on the session.

Username / password (Local & LDAP)#

# Default: HTTPS on port 8443, prompts for credentials (Local/LDAP)
Connect-Athena -Server "athena.contoso.com"

# Custom port
Connect-Athena -Server "athena.contoso.com" -Port 443

# Non-interactive with a stored credential
$cred = Get-Credential -UserName "admin"
Connect-Athena -Server "athena.contoso.com" -Credential $cred

# Return the session object instead of just storing it
$session = Connect-Athena -Server "athena.contoso.com" -PassThru
$session.AuthProvider   # Local or Ldap

Keycloak SSO (device-code flow)#

Add -Keycloak to sign in through Keycloak using the OIDC device-code grant. This flow is browserless on the console side: Connect-Athena requests a device and user code from the Keycloak realm, prints a verification URL and user code for you to approve in a browser, then polls for the token and exchanges it at the server for an Athena session. The three Keycloak parameters are operator-supplied — there is no anonymous server endpoint that hands them out.

# Keycloak SSO: approve the shown user code in a browser, then the CLI gets a session
Connect-Athena -Server "athena.contoso.com" -Keycloak `
    -Issuer "https://kc.contoso.com/realms/athena" `
    -ClientId "athena-cli"

The session that comes back is byte-identical in shape to a password login — a JWT bearer token reused by every other cmdlet — with its AuthProvider set to Keycloak.

Parameters#

Connect-Athena takes these parameters. -Credential belongs to the default (username/password) parameter set; -Keycloak, -Issuer and -ClientId belong to the Keycloak set and are all required together.

Inspect or end the session with the other two session cmdlets. Disconnect-Athena calls api/auth/logout (so the sign-out is recorded in the audit log) and clears the stored session.

# See the current session, including its expiry
Get-AthenaSession

# Log out and clear the cached token
Disconnect-Athena

Command browser#

Every cmdlet in the module, side by side with its reference. Pick a command in the list on the left — filter by name, synopsis or -Parameter and narrow by category — and its syntax, description, parameters and examples appear on the right. This index is generated from the module source; for the authoritative, version-specific set on your own server run Get-Command -Module Athena.

Common tasks#

Find agents and filter the fleet

Get-AthenaAgent supports lookup by -Id or -Hostname, filtering by -Tag, -Status (Online, Offline, Pending, Maintenance) or a free-text -Search, and -All to page through the whole estate.

# Only the online agents
Get-AthenaAgent -Status Online

# Everything with a given tag, exported to CSV
Get-AthenaAgent -Tag "production" | Export-Csv agents.csv

# A single agent by hostname
Get-AthenaAgent -Hostname "SERVER01"

Run a command across targets

Invoke-AthenaCommand queues a remote command to agents selected by -TargetAgentIds or -TargetTags, and accepts agents straight off the pipeline. The -Type is one of PowerShell (default), Batch, Shell, Executable, Python or Chocolatey, and -TimeoutSeconds defaults to 300.

# Pipe production agents into a command
Get-AthenaAgent -Tag "production" |
  Invoke-AthenaCommand -Command "Get-Service -Name Spooler"

# A longer batch job with an explicit timeout
Invoke-AthenaCommand -Command "maintenance.bat" -Type Batch `
  -TimeoutSeconds 600 -TargetTags "web-server"

Query the audit log

# Login failures from the last 7 days, all pages, to CSV
Get-AthenaAudit -EventType "LoginFailure" `
  -FromDate (Get-Date).AddDays(-7) -All |
  Export-Csv login-failures.csv

Scripted health check

Get-AthenaHealth works without a session — pass it a -Server directly — which makes it convenient for unattended monitoring.

$health = Get-AthenaHealth -Server "athena.contoso.com"
if ($health.OverallStatus -ne "healthy") {
    Write-Warning "Athena is $($health.OverallStatus)"
}

Roles & permissions#

The module calls the same endpoints as the console, so a token's role decides which cmdlets succeed. Calls outside your role are rejected by the server. As a rule of thumb:

• Helpdesk and up — read-oriented queries such as Get-AthenaAgent, Get-AthenaAudit and inventory cmdlets.
• Operator — operational actions like Invoke-AthenaCommand and running deployments.
• Admin — sensitive management such as PKI operations, user management and server settings.

See Roles & Permissions for the full role matrix. Check your own role with (Get-AthenaCurrentUser).Role.