# Helper scripts

## Overview

When bootstrapping a sandbox container or virtual machine, Instruqt injects some helper scripts. These scripts assist you in setting up the environment or applying check scripts. See the currently available set of [helper scripts](https://github.com/instruqt/participant-host-bootstrap/tree/master/bootstrap/bin/functions) on GitHub.

{% hint style="info" %}
Helper scripts assume the host has a POSIX shell available at`/bin/sh`.
{% endhint %}

This article covers the following helper scripts:

* `fail-message`
* `set-workdir`

## `fail-message`

The `fail-message` helper script provides feedback to the learner when writing check scripts. The function will write a given string to `stdout`, prefixed with `FAIL:`.

{% tabs %}
{% tab title="Bash" %}

```bash
fail-message "your fail message here..."
```

{% endtab %}
{% endtabs %}

Consider the following example:

{% tabs %}
{% tab title="Bash" %}

```bash
#!/bin/bash

if [ !$EVERYTHING_WENT_WELL ]; then
  fail-message "Your challenge failed because of REASON"
  exit 1
fi
```

Without the helper script, the format would be:

```bash
#!/bin/bash

if [ !$EVERYTHING_WENT_WELL ]; then
  echo "FAIL: Your challenge failed because of REASON"
  exit 1
fi
```

{% endtab %}
{% endtabs %}

## `set-workdir`

The `set-workdir` script can be used to change the active working directory for a terminal tab from a [challenge setup script](/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution.md#setup-scripts).

{% tabs %}
{% tab title="Bash" %}

```
set-workdir <dir>
```

{% endtab %}
{% endtabs %}

#### Example

Consider the following example, which sets the `usr` directory as the active working directory:

{% tabs %}
{% tab title="Bash" %}

```bash
#!/bin/bash

set-workdir usr
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The `set-workdir` script is implemented using `$HOME/.bashrc`. This means you will have to use `bash` as the shell for the container or virtual machine.

If you don't have `bash` available, you can achieve the same behavior by adding a `cd /path/to/workdir` command to the shell's profile (e.g. `$HOME/.profile` or `/etc/profile`).

When using the `ash` shell (which most `busybox` based containers do), you can also indicate that the `.bashrc` profile needs to be loaded. To do so, add an environment variable `ENV` with value `$HOME/.bashrc`. to the container's environment variables in the `config.yml`.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/sandboxes/lifecycle-scripts/helper-scripts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.