Instances CLI Commands

Manage bot instances through the command line interface.

Overview

The instances command allows you to list and retrieve information about running bot instances. All commands support multiple output formats for easy integration with scripts and tools.

Commands

list

List all bot instances.

Usage:

pow-desktop.exe instances list [OPTIONS]

Options:

• -o, --output <OUTPUT> - Output format (default: text)
  • Possible values: text, json, yaml

Examples:

# List all instances in text format (default)
pow-desktop.exe instances list

# List all instances in JSON format
pow-desktop.exe instances list --output json

# List all instances in YAML format
pow-desktop.exe instances list --output yaml

Output Fields:

• ID - Unique instance identifier
• NAME - Instance name
• STATUS - Current instance status (e.g., Running, Stopped)
• CREATED_AT - Timestamp when the instance was created
• SCRIPT_NAME - Name of the currently running script (if any)
• SCRIPT_STATE - Current state of the script (if any)
• RUNTIME_SECONDS - Total runtime in seconds

---

get

Get detailed information about a specific instance by ID.

Usage:

pow-desktop.exe instances get <ID> [OPTIONS]

Arguments:

• <ID> - The instance ID to retrieve

Options:

• -o, --output <OUTPUT> - Output format (default: text)
  • Possible values: text, json, yaml

Examples:

# Get instance details in text format
pow-desktop.exe instances get inst-123

# Get instance details in JSON format
pow-desktop.exe instances get inst-123 --output json

# Get instance details in YAML format
pow-desktop.exe instances get inst-123 --output yaml

Output Fields: Includes all fields from list plus:

• NOTES - Additional notes about the instance (if any)
• LOGS - Recent log entries (if available)

---

Output Formats

Text Format (Default)

Human-readable table format suitable for terminal viewing.

Example:

ID          NAME            STATUS    CREATED_AT
inst-123    My Bot          Running   2024-01-15T10:30:00Z

JSON Format

Structured JSON output suitable for programmatic processing.

Example:

[
  {
    "id": "inst-123",
    "name": "My Bot",
    "status": "Running",
    "created_at": "2024-01-15T10:30:00Z",
    "script_name": "my-script",
    "script_state": "running",
    "runtime_seconds": 3600
  }
]

YAML Format

YAML output for configuration files and human-readable structured data.

Example:

- id: inst-123
  name: My Bot
  status: Running
  created_at: "2024-01-15T10:30:00Z"
  script_name: my-script
  script_state: running
  runtime_seconds: 3600

---

Exit Codes

• 0 - Success
• 1 - Error (e.g., instance not found, database error)

---

Examples

List all running instances

pow-desktop.exe instances list

Get instance details and save to file

pow-desktop.exe instances get inst-123 --output json > instance.json

Filter instances using jq (JSON output)

pow-desktop.exe instances list --output json | jq '.[] | select(.status == "Running")'

Monitor instance status

# Check instance status every 5 seconds
while true; do
  pow-desktop.exe instances get inst-123 --output text
  sleep 5
done

---