Manage bot instances through the command line interface.

The instances command allows you to create, list, and manage bot instances and their scripts. All commands support multiple output formats for easy integration with scripts and tools.

All CLI commands support the following global option:

• --api-host <URL> - API host URL (overrides POW_API_URL environment variable)

pow-desktop.exe --api-host http://localhost:8080 instances 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

---

Create a new bot instance. Launches a game client and optionally logs in with an account, connects through a proxy, and starts a script.

Usage:

pow-desktop.exe instances create [OPTIONS]

Options:

• --account-id <ACCOUNT_ID> - Account ID to use (omit for manual login)
• --character-id <CHARACTER_ID> - Character ID for OAuth accounts
• --proxy-id <PROXY_ID> - Proxy ID to use
• --script-id <SCRIPT_ID> - Script ID to start after launch (mutually exclusive with --script-path)
• --script-path <SCRIPT_PATH> - Local script path to start after launch (mutually exclusive with --script-id)
• --upload - Upload script as base64-encoded ZIP (use with --script-path)
• --profile-id <PROFILE_ID> - Profile ID to load for the script (use with --script-id)
• --fps-limit <FPS_LIMIT> - FPS limit (e.g. 15, 30). Omit or set to 60 for default.
• -o, --output <OUTPUT> - Output format (default: text)
  • Possible values: text, json, yaml

Examples:

# Create an instance with manual login (no account)
pow-desktop.exe instances create

# Create an instance with a specific account
pow-desktop.exe instances create --account-id acc-123

# Create an instance with account, proxy, and script
pow-desktop.exe instances create --account-id acc-123 --proxy-id proxy-1 --script-id script-456

# Create an instance with a local script uploaded as ZIP
pow-desktop.exe instances create --account-id acc-123 --script-path ./my-script --upload

# Create an instance with FPS limit
pow-desktop.exe instances create --account-id acc-123 --fps-limit 15

Output Fields: Same as list command.

---

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)

---

The following commands operate on a specific instance. Use the syntax:

pow-desktop.exe instances <ID> <COMMAND>

(You can also use instances instance <ID> <COMMAND>; both work.)

Execute Lua code in the instance.

Usage:

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

Arguments:

• <ID> - The instance ID
• <CODE> - Lua code to execute

Options:

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

Examples:

# Execute Lua code (text output returns result directly)
pow-desktop.exe instances inst-123 exec "return 1 + 1"

# Get structured response in JSON
pow-desktop.exe instances inst-123 exec "return players.local_player():name()" --output json

Text Output: Returns the result string directly, or the error string if execution failed.

JSON/YAML Output Fields:

• session_id - The Lua session ID
• result - Result string (if successful)
• error - Error string (if failed)

---

Start a script on the instance.

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

• --script-id <SCRIPT_ID> - Script ID to start (mutually exclusive with --script-path)
• --script-path <SCRIPT_PATH> - Local script path (mutually exclusive with --script-id)
• --upload - Upload script as base64-encoded ZIP (use with --script-path)
• --profile-id <PROFILE_ID> - Profile ID to use with the script
• -o, --output <OUTPUT> - Output format (default: text)
  • Possible values: text, json, yaml

Note: Exactly one of --script-id or --script-path must be provided.

Examples:

# Start a script by ID
pow-desktop.exe instances inst-123 start --script-id script-456

# Start a script by ID with a profile
pow-desktop.exe instances inst-123 start --script-id script-456 --profile-id prof-789

# Start a local script
pow-desktop.exe instances inst-123 start --script-path ./my-script.lua

# Upload and start a local script directory
pow-desktop.exe instances inst-123 start --script-path ./my-script --upload

Output Fields: Same as list command (returns updated instance summary).

---

Stop the currently running script on the instance.

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

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

Examples:

# Stop the running script
pow-desktop.exe instances inst-123 stop

# Stop and get JSON output
pow-desktop.exe instances inst-123 stop --output json

Output Fields: Same as list command (returns updated instance summary).

---

Pause the currently running script on the instance.

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

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

Examples:

# Pause the running script
pow-desktop.exe instances inst-123 pause

# Pause and get JSON output
pow-desktop.exe instances inst-123 pause --output json

Output Fields: Same as list command (returns updated instance summary).

---

Resume a paused script on the instance.

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

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

Examples:

# Resume a paused script
pow-desktop.exe instances inst-123 resume

# Resume and get JSON output
pow-desktop.exe instances inst-123 resume --output json

Output Fields: Same as list command (returns updated instance summary).

---

Terminate the instance (shuts down the game client).

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

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

Examples:

# Terminate an instance
pow-desktop.exe instances inst-123 terminate

# Terminate and get JSON confirmation
pow-desktop.exe instances inst-123 terminate --output json

Text Output:

Instance inst-123 terminated successfully

JSON Output:

{
  "id": "inst-123",
  "status": "terminated"
}

---

Capture a screenshot of an instance's game client window and save as PNG.

Usage:

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

Arguments:

• <ID> - The instance ID

Options:

• -o, --output <PATH> - Save screenshot to this file as PNG. Omit to print base64 to stdout.

Examples:

# Print base64 to stdout (default)
pow-desktop.exe instances inst-123 screenshot

# Save to a file
pow-desktop.exe instances inst-123 screenshot --output capture.png

---

Human-readable table format suitable for terminal viewing.

Example:

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

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 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

---

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

---

pow-desktop.exe instances create --account-id acc-123 --script-id script-456 --output json

pow-desktop.exe instances list

pow-desktop.exe instances inst-123 exec "return players.local_player():name()"

# Start a script
pow-desktop.exe instances inst-123 start --script-id script-456

# Pause when needed
pow-desktop.exe instances inst-123 pause

# Resume later
pow-desktop.exe instances inst-123 resume

# Stop the script
pow-desktop.exe instances inst-123 stop

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

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

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

pow-desktop.exe instances inst-123 terminate

pow-desktop.exe instances inst-123 screenshot --output screenshot.png