Basic Scripting¶

drpcli is designed to be scriptable. It reads connection details from environment variables, returns machine-readable JSON by default, and provides first-class commands for waiting on state changes — the key building blocks for automation scripts.

Environment Variables¶

Set these variables before calling drpcli so that credentials and endpoint are not hard-coded in scripts:

Bash

export RS_ENDPOINT="https://drp.example.com:8092"
export RS_TOKEN="<your-jwt-token>"      # Preferred: use a token
# export RS_KEY="username:password"    # Alternative: basic auth
export RS_SKIP_VERIFY=true              # Set if using a self-signed TLS cert

Obtain a token programmatically:

Bash

export RS_TOKEN=$(drpcli users token rocketskates ttl 3600 | jq -r .Token)

Error Handling¶

drpcli exits with a non-zero status code when a command fails. Always check return codes in scripts:

Bash

#!/bin/bash
set -euo pipefail

# Fail loudly if a machine does not exist
MACHINE=$(drpcli machines show "$MACHINE_UUID") || {
    echo "ERROR: machine $MACHINE_UUID not found" >&2
    exit 1
}

For operations that may fail non-fatally, capture the exit code explicitly:

Bash

if drpcli machines show "$MACHINE_UUID" > /dev/null 2>&1; then
    echo "Machine exists"
else
    echo "Machine not found, skipping"
fi

Waiting for State Changes¶

drpcli machines wait blocks until a machine field reaches the expected value or a timeout expires. This is the correct way to wait for provisioning events rather than polling in a sleep loop:

Bash

# Wait up to 30 minutes for the machine's stage to be set to complete
drpcli machines wait "$MACHINE_UUID" Stage complete 1800

# Wait for the machine to reach the "local" bootenv
drpcli machines wait "$MACHINE_UUID" BootEnv local 900

# Wait for a specific workflow to finish
drpcli machines wait "$MACHINE_UUID" WorkflowComplete true 1800

The wait command returns exit code 0 when the condition is met, and non-zero on timeout.

Looping Over Machines¶

Combine drpcli machines list with jq to iterate:

Bash

#!/bin/bash
# Apply a profile to all machines currently in the "discover" stage

drpcli machines list Stage=discover | jq -r '.[].Uuid' | while read -r UUID; do
    echo "Adding profile to $UUID ..."
    drpcli machines addprofile "$UUID" my-config-profile
done

Setting and Reading Parameters¶

Bash

# Set a single parameter on a machine
drpcli machines set "$MACHINE_UUID" param my-param to '"value"'

# Read a parameter from a machine
VALUE=$(drpcli machines get "$MACHINE_UUID" param my-param)

# Remove a parameter
drpcli machines remove "$MACHINE_UUID" param my-param

Complete Example Script: Provision and Wait¶

The following script assigns a workflow to a machine, waits for it to complete, and reports the result:

Bash

#!/bin/bash
set -euo pipefail

MACHINE_UUID="${1:?Usage: $0 <machine-uuid> <workflow>}"
WORKFLOW="${2:?Usage: $0 <machine-uuid> <workflow>}"
TIMEOUT=3600   # 60 minutes

export RS_ENDPOINT="${RS_ENDPOINT:-https://drp.example.com:8092}"
export RS_TOKEN="${RS_TOKEN:?RS_TOKEN must be set}"

echo "Assigning workflow '$WORKFLOW' to machine '$MACHINE_UUID' ..."
drpcli machines update "$MACHINE_UUID" "{\"Workflow\":\"$WORKFLOW\"}"

echo "Waiting up to $TIMEOUT seconds for workflow to complete ..."
if drpcli machines wait "$MACHINE_UUID" WorkflowComplete true "$TIMEOUT"; then
    echo "Workflow completed successfully."
    STAGE=$(drpcli machines show "$MACHINE_UUID" | jq -r .Stage)
    echo "Final stage: $STAGE"
else
    echo "ERROR: Workflow did not complete within $TIMEOUT seconds." >&2
    drpcli machines show "$MACHINE_UUID" | jq '{Stage:.Stage,Task:.CurrentTask}'
    exit 1
fi

Call the script as:

Bash

RS_TOKEN=$(drpcli users token rocketskates ttl 7200 | jq -r .Token) \
  ./provision.sh <machine-uuid> ubuntu-22-04-install

See Basic Reporting for reporting patterns that complement these scripting techniques.