← Library
REF 14 Cheat Sheet · Reference

Common library reference

Helper commands shipped on Instruqt-published images. Available in every lifecycle script. Raw upstream Docker images may not have them — guard accordingly.

Signatures Available on Instruqt-published images
fail-message "..." Render a learner-facing failure message in the UI. Pair with exit 1.
set-status "..." Pass-side counterpart. Render at the end of a passing check, before exit 0.
agent variable set KEY VALUE Store a key-value pair. Visible to all subsequent scripts on every host and to the body via [[ Instruqt-Var ]].
agent variable get KEY Read a previously set value. Common in cleanup to retrieve resource IDs for deletion.
set-workdir /path Set the default working directory for terminal tabs on this host. Per-tab workdir: in assignment.md overrides this.
$INSTRUQT_AUTH_TOKEN Env var. Ephemeral JWT for the Instruqt REST API. Use to query track state or trigger platform actions from inside the sandbox.
Output messaging fail-message + set-status

Surface check results to the learner. Pair both for consistent fail/pass UX.

if ! cond_a; then fail-message "Run X first." exit 1 fi if ! cond_b; then fail-message "Y is missing." exit 1 fi set-status "All checks passed." exit 0
State agent variable + set-workdir

Bridge values between scripts and the body, and set per-host terminal default directory.

URL=$(generate_url) agent variable set DB_URL "$URL" set-workdir /workspace # Read in another script: URL=$(agent variable get DB_URL)
Reliability retry patterns

No built-in retry helper. Two common patterns.

# Inline flat retry for i in $(seq 1 30); do curl -fsS http://api/health \ && break sleep 2 done # Standalone /usr/local/bin/retry # wrapper (ship in track_scripts): retry curl -fsS http://api/health
Some workshop-image families bundle a sourceable bash library with a retry function and other helpers. source at the top of setup; call by name. Saves reimplementing common patterns.
Auth token Platform REST API

Authenticate calls to Instruqt's REST API from inside the sandbox without a separate API key.

Ephemeral — bound to the current play session. Use in advanced certification or telemetry-enabled tracks where scripts query track state programmatically.

curl -H \ "Authorization: Bearer \ $INSTRUQT_AUTH_TOKEN" \ https://play.instruqt.com/api/...
When helpers are missing Raw Docker base images

Stock ubuntu:22.04, python:3.11-slim, and similar upstream images don't ship the helpers.

fail-message "..." || true set-status "..." || true
Heuristic: Instruqt-published containers and platform-published VMs always have helpers. Stock GCP cloud images (Ubuntu, Rocky, Debian) acquire them during bootstrap. Raw upstream Docker images often don't. When in doubt, guard.
Notes