Commands library

Quick guide #

Commands Library is a centralized repository for reusable commands that can be executed on managed devices. It lets you standardize common operational tasks (e.g., troubleshooting, data collection, quick checks) by storing commands in one place and reusing them across the environment. Commands can be created for different runtimes such as PowerShell, PowerShell Core, Bash/Shell, or CMD.

Add a new Command #

1. Click + Add Command.
2. Enter a Command name.
3. Select the Type (e.g., PowerShell Core, PowerShell, Bash/Shell, CMD).
4. (Optional) Add Tags and a Description.
5. Paste or write the Command content.
6. Click Add to create the command.

Edit a Command #

1. Open the command (e.g., via the Details / eye icon).
2. In the Current version panel, click Edit.
3. Update the command content and/or metadata as needed.
4. Save the changes (a new version is created).

Delete a Command #

1. Click the Delete (trash) icon next to the command.
2. Confirm deletion.

Additional useful information #

OS compatibility #

Some command types are OS-specific. Use Tags (e.g., windows, linux) and/or naming conventions to clearly indicate the target platform.

Prefer non-interactive commands #

Avoid prompts and UI interactions; commands should run unattended.

Keep output readable #

Return clear, structured output (and include error handling) to simplify troubleshooting and auditing.

Technical documentation #

The Commands Library is XOAP’s centralized store for versioned and reusable commands that can be executed on managed devices through the XOAP Inventory/Connector execution layer. It is designed for operational tasks such as troubleshooting, validation checks, log collection, and lightweight remediation actions.

A command in the library is defined by:

• Metadata (name, description, tags)
• Runtime type (PowerShell, PowerShell Core, Bash/Shell, CMD)
• Command body (the actual script/command text)
• Version information (version number and message)

Commands are executed on devices that have the XOAP Connector installed.

Command Types (Runtime) #

When you create a command, you select a Type that defines the interpreter/runtime used on the device:

• PowerShell
  Runs using Windows PowerShell (typically 5.1 on Windows).
• PowerShell Core
  Runs using PowerShell 7+ (cross-platform when available).
• Bash/Shell
  Runs using a shell on Linux/macOS (typically /bin/bash or /bin/sh, depending on the device).
• CMD
  Runs using Windows Command Prompt (cmd.exe).

Versioning behavior #

Commands are versioned artifacts. Any change to the command definition (especially the command body) should be treated as a new version so you can:

• Track who changed what and why
• Roll forward safely
• Keep operational actions reproducible across environments

Best practice: Use short, meaningful version messages (e.g., “Add service filter”, “Fix path quoting”, “Support PS7”).

Fields and what they mean #

In the Add Command dialog:

• Command name
  Unique, human-readable identifier. Use a consistent naming scheme like:
  windows-check-service-status / linux-journalctl-last-50
• Type
  The runtime/interpreter used to execute the command on the target device.
• Tags
  Used for filtering and organization (OS, purpose, team, environment).
• Description (optional)
  Short explanation of intent, expected output, and any prerequisites.
• Command
  The script/command content. This should be non-interactive and safe to run repeatedly.

Execution model and output #

Commands are  executed remotely and return:

• Exit code (success/failure)
• Standard output (results)
• Standard error (errors)

Recommended patterns #

• Return human-readable output plus simple structured output where possible (key/value lines).
• Use explicit exit codes:
  • 0 = success
  • non-zero = failure or partial failure
• Write errors to stderr and keep stdout for normal results.

Operational and security considerations #

Non-interactive only #

• Avoid prompts (Read-Host, pause, interactive confirmation).
• Assume the command runs unattended.

Idempotency #

• Prefer commands that can be run multiple times without harmful side effects.
• For remediation-type commands, check current state before changing it.

Logging #

• For troubleshooting commands, include contextual details (hostname, timestamp, relevant versions).

Best practices for building a maintainable library #

• Naming convention: os-purpose-action (e.g., windows-inventory-installed-software)
• Tagging: OS + team + category (e.g., windows, security, troubleshooting)
• Small scope: One command = one purpose. Avoid “do everything” scripts.
• Document prerequisites: Required tools, modules, permissions, or paths.
• Test on pilots: Validate on a small set of devices before broad use.
• Prefer PowerShell Core for cross-platform: If your fleet supports it, it simplifies reuse.

Examples (simple, safe commands) #

PowerShell (Windows) – list a service state #

Get-Service -Name “WinRM” | Select-Object Name, Status, StartType

PowerShell (Windows) – last 50 event log errors (System) #

Get-WinEvent -LogName System -MaxEvents 50 |
  Where-Object { $_.LevelDisplayName -in “Error”,”Critical” } |
  Select-Object TimeCreated, Id, ProviderName, Message

CMD (Windows) – basic network info #

ipconfig /all

Bash (Linux) – disk usage summary #

df -h

Troubleshooting #

If a command fails to run or returns unexpected output, the most common causes are:

• Wrong Type selected (e.g., Bash command on Windows)
• Runtime not installed (e.g., PowerShell 7 missing for “PowerShell Core” commands)
• OS differences (paths, tools, service managers)
• Command is interactive or expects a TTY

Recommendation: Start with read-only diagnostics commands, then add remediation actions only after validation and clear approvals.