Remote Command Execution

Run a command once, on demand, across any set of agents — a quick Get-Process on one machine, or a remediation script on every workstation with a tag. Athena queues the command, dispatches it to the targeted agents, and collects a per-agent result with exit code, standard output and standard error so you can see exactly how each machine responded. Drive it from the console, the REST API, or the PowerShell module.

This page is the reference for the command lifecycle — creating, running, cancelling, retrying and reading results. For the broader picture of remote work (interactive desktop, screen share) see Remote Commands & Desktop; to save and reuse frequently-run scripts see Command Templates; to run commands automatically on a schedule see Scheduled Jobs.

How command execution works#

A command is a single unit of work with one or more targets. When you create a command it starts in the Pending state; when you execute it, the server dispatches it to every currently-connected target agent and tracks a separate result for each one. The command as a whole and each per-agent result carry their own status, so a command that succeeds on nine machines and fails on the tenth shows exactly that.

Working from the Commands screen in the console, Execute Command creates and dispatches in a single step — you compose the command, pick the run-as identity and targets, and it goes out immediately. Over the API the two steps are separate endpoints (create, then execute), which lets you stage a command and dispatch it later.

Viewing command history in the console is available to the Helpdesk, Operator and Admin roles. Creating, executing, cancelling and retrying commands requires Operator or Admin; deleting a command requires Admin. See Roles & Permissions.

Command types#

Every command has a type that tells the agent how to run it:

Alongside the command text you can supply arguments, a workingDirectory, and a timeoutSeconds (default 300 seconds / 5 minutes). A command that exceeds its timeout is recorded as TimedOut.

Targeting agents#

You must specify at least one target. There are two ways to do it, and you can combine them:

A request with no targetAgentIds and no targetTags is rejected. Tag targeting is resolved at execution time, so a tagged command reaches whichever agents carry the tag when it runs.

Run-as identity#

By default a command runs as SYSTEM on the agent. To run it as a specific account instead, reference a stored credential by its credentialId from the Credential Vault; the agent decrypts and uses it just for that run. Choosing a credential turns off the SYSTEM default (runAsSystem becomes false).

Command status & lifecycle#

Both the overall command and each per-agent result move through the same set of states:

The actions available depend on the current status:

Attempting an action outside these rules is rejected — for example you cannot execute a command that has already run, and a Running command must be cancelled before it can be deleted. Retry does not resurrect the original command; it clones its type, text, arguments, targets and run-as identity into a new command.

Per-agent results#

Opening a command shows one result row per targeted agent. Each result includes:

A Skipped result also carries the maintenance details — the reason, who enabled maintenance mode, when, and when it ends — so you know why a machine was passed over and when it will be reachable again.

Using the API#

Create a command by posting its definition. This example runs a PowerShell command on two specific agents as SYSTEM, with a 5-minute timeout:

POST /api/commands
{
  "commandType": "PowerShell",
  "command": "Get-Process | Select-Object -First 10",
  "timeoutSeconds": 300,
  "targetAgentIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "runAsSystem": true
}

Target a whole group by tag, and run under a stored credential instead of SYSTEM:

POST /api/commands
{
  "commandType": "PowerShell",
  "command": "Restart-Service -Name Spooler",
  "targetTags": ["print-servers"],
  "credentialId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Creating a command leaves it in Pending. Dispatch it with a follow-up call:

POST /api/commands/{id}/execute

Command endpoints#

All command endpoints require authentication; creating and running commands requires the Operator or Admin role, and deletion requires Admin. See the API Reference.

PowerShell#

The Athena PowerShell module runs and manages commands. Unlike the raw API, Invoke-AthenaCommand creates the command for you in one call; combine it with agent queries to target by pipeline:

# Run a PowerShell command on two specific agents
Invoke-AthenaCommand -Command "Get-Process | Select-Object -First 10" `
    -TargetAgentIds $id1, $id2

# Run on every agent carrying a tag
Invoke-AthenaCommand -Command "Get-Service" -TargetTags "production", "web-server"

# A batch command with a 10-minute timeout
Invoke-AthenaCommand -Command "dir C:\Windows" -Type Batch `
    -TimeoutSeconds 600 -TargetAgentIds $id1

# Run under a stored credential instead of SYSTEM
Invoke-AthenaCommand -Command "script.ps1" -CredentialId $credId `
    -TargetAgentIds $id1

# Target by pipeline — every production agent
Get-AthenaAgent -Tag "production" | Invoke-AthenaCommand -Command "Get-Date"

Listing, inspecting and managing commands:

# List and filter commands
Get-AthenaCommand
Get-AthenaCommand -Status Running
Get-AthenaCommand -Type PowerShell -Search "Restart-Service"

# Get one command (with its per-agent results), or all for an agent
Get-AthenaCommand -Id $commandId
Get-AthenaCommand -AgentId $agentId

# Cancel, retry, and remove
Stop-AthenaCommand -Id $commandId    # cancel
Redo-AthenaCommand -Id $commandId    # retry (new command)
Remove-AthenaCommand -Id $commandId

# Dashboard counts
Get-AthenaCommandStats

Auditing#

Every command action is written to the audit log — creating, executing, cancelling, retrying and deleting — with the command, the acting user, and the action taken. Because ad-hoc commands run code on your endpoints, this trail is the record of who ran what, and when.