> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/shark-jack-display/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/shark-jack-display/interactive-duckyscript.md).

# Interactive DuckyScript

The following are interactive DuckyScript commands which display on-screen and may accept user input.

## ALERT

This displays a full screen flashing alert on the screen that can be dismissed by user input or will auto dismiss after defined timeout.

`ALERT` will (attempt to) auto split and center text. For advanced formatting/manual control, pass true as the last argument

### Usage

```
Alert "Title" (optional timeout) (optional flash flag) (optional raw input flag)
```

### Example

```
ALERT "Example flashing alert" 10
```

The text "Example flashing alert" flashes on screen for 10 seconds, or until dismissed by user input.

```
ALERT "Example static alert" false
```

The text "Example static alert" displays on screen without flashing.<br>

{% hint style="info" %}
A timeout of 0s will mean alert will persist on screen until drawn over, and will not consume button input.
{% endhint %}

## BLOCKING\_ALERT

The `BLOCKING_ALERT` command displays a full screen flashing alert on the screen that **CANNOT** be dismissed by user input and will only dismiss after defined timeout.

`BLOCKING_ALERT` will (attempt to) auto split and center text. For advanced formatting/manual control, pass true as the last argument.

{% hint style="info" %}
usage of an optional argument requires passing previous optional arguments
{% endhint %}

### Usage

```
BLOCKING_ALERT "Title" (optional timeout)
```

### Example

```
BLOCKING_ALERT "This cannot be dismissed for 10 seconds" 10
```

The text "This cannot be dismissed for 10 seconds" flashes on screen for 10 seconds and cannot be dismissed by user input.

```
BLOCKING_ALERT "This cannot be dismissed for 5 seconds and will not flash" 5 false
```

The text "This cannot be dismissed for 5 seconds and will not flash" will display on screen, without flashing, for 5 seconds and cannot be dismissed by user input.

## CLEAR\_SCREEN

Clears the screen. Similar to `cls` for DOS or `clear` for linux.

### Usage

```
CLEAR_SCREEN
```

### Example

```
CLEAR_SCREEN
```

The screen will become blank.

## CONFIRMATION\_DIALOG

The `CONFIRMATION_DIALOG` command will prompt the user to confirm/accept.

### Usage

```
CONFIRMATION_DIALOG "Are you sure?" "Yes"
```

\
The `CONFIRMATION_DIALOG` command will echo `"← Back"` if canceled by the user. Otherwise, `CONFIRMATION_DIALOG` will echo the affirmative label if it is selected by the user.

{% hint style="info" %}
By default that value is "Confirm", unless otherwise passed by 2nd argument.
{% endhint %}

### Example

```
CONFIRMATION_DIALOG "Are you sure?"
```

The Shark Jack will prompt the user with "Are you sure?" along with two options: "Back" and "Confirm".

```
CONFIRMATION_DIALOG "Warp speed?" "Make it so"
```

The Shark Jack will prompt "Warp speed?" along with the two options: "Back" and "Make it so"

## COUNTDOWN

The `COUNTDOWN` command will display a flashing countdown waiting for user input. If the user presses the button before the timeout is up, the script will echo `"Cancelled"`. Otherwise the script will echo `"Timeout"`.

### Usage

```
COUNTDOWN "Countdown Title" 10
```

### Example

```
COUNTDOWN "Engaging Warp Drive" 5
```

The Shark Jack will display "Engaging Warp Drive", flashing, while counting down from 5 seconds, while displaying "Press button to cancel".

## IP\_PICKER

The `IP_PICKER` command is used to prompt the user to enter an IP address. The command will automatically pad, prompt, strip, validate, and then prompt the user for confirmation before echoing the final value. The command also includes automatic retry logic.

{% hint style="info" %}
The command will echo `"← Back"` if user exits early.
{% endhint %}

### Usage

```
IP_PICKER "Subnet?" "255.255.255.0"
```

### Example

```
IP_PICKER "IP Address?" "192.168.1.1"
```

The Shark Jack will display "IP Address?" followed by an IP prompt, pre-populated with "192.168.1.1", along with "Back" and "Save" options.

## LIST\_PICKER

The `LIST_PICKER` command will prompt the user to select an option from a predefined list.

### Usage

```
LIST_PICKER  <title> <space delimited list> <default value>
```

{% hint style="info" %}
The command will echo the selected value, or `"← Back"` upon selection.
{% endhint %}

### Example

```
LIST_PICKER "Timeout" "1s 2s 3s 4s 5s 10s 15s 30s 60s" "10s"
```

The Shark Jack will display the title "Timeout" along with a list containing "1s" through "60s" with "10s" being pre-selected and the options "Back" and "Save"

## LOG

The `LOG` command is similar to `SCREEN_WRITE` and is used to add a message to the payload log. Unlike `SCREEN_WRITE` however, it will not automatically redraw the current payload log viewing window.

### Usage

```
LOG "<log line>"
```

### Example

```
LOG "Hello World"
```

The text "Hello World" will be added to the Payload Log without interrupting the screen.

## NUMBER\_PICKER

The `NUMBER_PICKER` command is used to prompt the user with a multi-character number picker, along with the options Back and Save.

### Usage

```
NUMBER_PICKER <title> <number>
```

{% hint style="info" %}
The `NUMBER_PICKER` command skips all non-numeric characters in the provided number.
{% endhint %}

### Example

```
NUMBER_PICKER "Subnet" "255.255.255.0"
```

The Shark Jack will display the title "Subnet" along with an interactive element allowing the user to change each digit of the provided number, "255.255.255.0"

```
NUMBER_PICKER "Pairing Code" "1-2-3-4"
```

In this example, the user will have the ability to change the digits 1, 2, 3 and 4. The dash ("`-`") characters will be skipped.

## OPTION\_DIALOG

The `OPTION_DIALOG` command will prompt the user to choose between two options.

Usage

```
OPTION_DIALOG <title> <first option> <second option>
```

{% hint style="info" %}
The command will echo the selected value.
{% endhint %}

### Example

```
OPTION_DIALOG "Hack The Planet?" "False" "True"
```

The Shark Jack will display the title "Hack The Planet?" along with the options "False" and "True"

## PROGRESS\_BAR

The PROGRESS\_BAR commands set allows for displaying a dynamically updating progress bar to the user. The command set includes:

* `CREATE_PROGRESS_BAR`
* `INCREMENT_PROGRESS`
* `SET_PROGRESS`

In order to use `INCREMENT_PROGRESS` and `SET_PROGRESS`, a progress bar must first be created with the `CREATE_PROGRESS_BAR` command.

The `INCREMENT_PROGRESS` command adds to the current total progress, while the `SET_PROGRESS` command will set the exact progress amount.

{% hint style="info" %}
The progress bar will automatically dismiss when the progress reaches 100.
{% endhint %}

### Usage

```
CREATE_PROGRESS_BAR <title>
INCREMENT_PROGRESS <value>
SET_PROGRESS <value>
```

### Example

```
SCREEN_WRITE "loading"

sleep 1

# Create progress bar with title "Loading..."
CREATE_PROGRESS_BAR "Loading..."

sleep 1

# Add 10 the progress state
INCREMENT_PROGRESS 10

sleep 1

INCREMENT_PROGRESS 10

sleep 1

# Set the progress state to 70
SET_PROGRESS 70

sleep 0.5
SET_PROGRESS 80
sleep 0.5
SET_PROGRESS 90
sleep 0.5
SET_PROGRESS 100

sleep 1

SCREEN_WRITE "Complete"
```

## SCREEN\_WRITE

The `SCREEN_WRITE` command will write text to the payload log.

### Usage

```
SCREEN_WRITE "text"
```

### Example

```
SCREEN_WRITE "Test 1"
sleep 0.25
SCREEN_WRITE "Test 2"
sleep 0.25
SCREEN_WRITE "Test 3"
sleep 0.25
SCREEN_WRITE "Test 4"
sleep 0.25
SCREEN_WRITE "Test 5"
sleep 0.25
SCREEN_WRITE "Test 6"
sleep 0.25
SCREEN_WRITE "Test 7"
sleep 0.25
SCREEN_WRITE "Test 8"
sleep 0.25
SCREEN_WRITE "Test 9"
sleep 0.25
SCREEN_WRITE "Test 10"
```

The payload will write "Test 1" through "Test 10" on the screen with quarter-second delays between each.

## SINGLE\_NUMBER\_PICKER

Similar to `NUMBER_PICKER`, the `SINGLE_NUMBER_PICKER` will allow the user to select a number, but this one will auto adjust the character width, allowing the user to go past 9 into double digits, etc.

Similar to `NUMBER_PICKER` it skips special characters, ignoring non-numberic leading or trailing characters.

### Usage

```
SINGLE_NUMBER_PICKER <title> <number>
```

The `SINGLE_NUMBER_PICKER` supports a interval parameter. For example:&#x20;

```
SINGLE_NUMBER_PICKER "Seconds" "60" "30"
```

### Example

```
SINGLE_NUMBER_PICKER "CIDR" "/24"
```

Prompts the user for a subnet in CIDR notation. The `/` character is ignored.

```
NUMBER_PICKER "Ping Replies?" "3"
```

The Shark Jack will display the title "Ping Replies?" along with an interactive element allowing the user to select a number, beginning with 3.

## SPINNER

The SPINNER command set allows for displaying a title and "spinning line" graphic. It is typically used to indicate to the user that a long running process is ongoing. The command set includes:

* `CREATE_SPINNER`
* `STOP_SPINNER`

### Usage

```
CREATE_SPINNER <title>
STOP_SPINNER
```

### Example

```
# Create an indeterminate spinner on screen
# Spinner functions:
# CREATE_SPINNER <title>
# STOP_SPINNER

SCREEN_WRITE "Creating spinner"

sleep 1

CREATE_SPINNER "Loading..."

sleep 5

STOP_SPINNER

SCREEN_WRITE "Done"
```

## TEXT\_PICKER

The `TEXT_PICKER` command can be used to prompt for a fixed width string with a max of 16 characters. You can define a custom alphabet to restrict the user's options. You can also provide a space padded string to allow for a "dynamic width" string, provided your code handles trimming the string afterwards.

### Usage

```
TEXT_PICKER "Title" "default_value" "custom_alphabet"
```

### Example

```
TEXT_PICKER "Set MAC:" "$mac" "0123456789abcdef"
```

This text picker with custom alphabet only allows the user to enter hex characters.

```
# text picker with default (full) alphabet
resp="$(TEXT_PICKER "Name" "dade")"
if [ "$resp" = "← Back" ]; then
  SCREEN_WRITE "Cancelled"
else
  SCREEN_WRITE "Hello, $resp"
fi
```

This text picker allows for usage of the full alphabet.

## WAIT\_FOR\_BUTTON

The `WAIT_FOR_BUTTON` command set allows you to pause further payload execution until a button is pressed. The command set includes:

* `WAIT_FOR_BUTTON` and its aliases `WAIT_FOR_BUTTON_PRESS` and `WAIT_FOR_BUTTON_MIDDLE`
* `WAIT_FOR_BUTTON_DOWN` and its alias `WAIT_FOR_BUTTON_LEFT`
* `WAIT_FOR_BUTTON_UP` and its alias `WAIT_FOR_BUTTON_RIGHT`

### Usage

```
SCREEN_WRITE "Wait for user to press up"
WAIT_FOR_BUTTON_UP
SCREEN_WRITE "The user pressed up"
```

### Example

```
SCREEN_WRITE "Wait for up"
sleep 1

WAIT_FOR_BUTTON_UP
# WAIT_FOR_BUTTON_RIGHT

SCREEN_WRITE "Done"

sleep 1


SCREEN_WRITE "Wait for down"
sleep 1

WAIT_FOR_BUTTON_DOWN
# WAIT_FOR_BUTTON_LEFT

SCREEN_WRITE "Done"

sleep 1


SCREEN_WRITE "Wait for middle"
sleep 1

WAIT_FOR_BUTTON_MIDDLE
# WAIT_FOR_BUTTON

SCREEN_WRITE "Done"

sleep 1


SCREEN_WRITE "Wait for ANY"
sleep 1

# Using 0 seconds for the timeout means alert will not consume the button input
ALERT "press ANY to continue" 0 false

resp="$(WAIT_FOR_INPUT)"

SCREEN_WRITE "$resp"

SCREEN_WRITE "Done"
```