One script language for both. A macro is played by the console in your browser and stops if the tab closes. A runbook is run by the device itself: it can wait for words on the screen, and it carries on with the browser closed.
One command per line, # starts a comment, blank lines are
ignored. Case does not matter for the commands or the key names.
key chord | press the chord and let go: key f2, key ctrl+alt+del, key shift+tab |
type text | type the rest of the line as characters |
delay ms | pause for that many milliseconds |
Runbooks add three more:
wait phrase | hold until a row of the screen contains the phrase |
gone phrase | hold until no row contains it |
timeout seconds | how long the waits below it may take; 60 if unsaid |
A wait that runs out stops the runbook at that line, and the panel says
so. The device reads the screen as characters, so a wait only ever sees a
text screen — a BIOS, a boot menu, a boot loader, a console. On a
picture, wait runs out and gone is satisfied at
once. Phrases are matched within one row, case is ignored, and a phrase
is at most 63 ASCII characters.
A chord is one key and any number of modifiers, joined with
+. Modifiers: ctrl (or control),
shift, alt (or option),
gui (or win, cmd,
super, meta).
| letters and digits | a .. z, 0 .. 9 |
| function keys | f1 .. f12 |
| the usual | enter / return, esc / escape, tab, space, backspace |
| arrows | up, down, left, right |
| navigation | home, end, pageup / pgup, pagedown / pgdn, insert / ins, delete / del |
| punctuation | minus, equal — the - and = keys |
| locks and the rest | capslock, scrolllock, pause, printscreen / prtsc / sysrq |
The key is a position, not a character: key a presses the key
that is a on a US keyboard, whatever the target’s layout
says it is.
A modifier on its own is a keypress too: key gui taps the
Windows key, key ctrl+shift holds and releases both.
You can also paste a Hak5 DuckyScript and it runs as-is — the same payloads written for a Rubber Ducky. It is recognised by its upper-case verbs, so nothing has to be switched; put it in the same box.
REM text | a comment |
STRING text | type the text |
STRINGLN text | type the text and press Enter |
DELAY ms | pause |
DEFAULT_DELAY ms | pause that much after every command below it |
REPEAT n | do the line before this one n more times |
GUI r, CTRL ALT DELETE, ENTER | a chord or a key: modifiers (GUI/WINDOWS, CTRL, ALT, SHIFT) and one key, space-separated |
Only the keyboard is covered. STRING is US ASCII, like
type. DuckyScript cannot wait for the screen — for that
use a runbook in the language above.
type is different in the two places. A macro sends each
character through the keyboard layout chosen in Settings → Input, so
it can type what that layout can. A runbook runs on the device, which has
no layout tables: it types printable US ASCII only, and the editor refuses
a line with anything else.
A runbook has at most 64 steps, a delay is 1 to 60000 ms, a
timeout 1 to 3600 s. All the runbooks together must fit in
3000 bytes, all the macros in 2000; the editor says when they do not.
The Automation panel can also fire a runbook, or a single action, on a
timetable. A schedule is a five-field cron line - minute hour
day-of-month month weekday - and an action. 0 7 * * 1-5
is 07:00 on weekdays; */15 * * * * is every fifteen minutes.
The action is Wake-on-LAN, an ATX button (power, reset, force-off), a named
runbook, or a restart of the device. Schedules need the wall clock, which
the device sets over SNTP — point it at a time server on the local
network if there is no internet. Until the clock is set nothing fires, and
the panel says so. Times are in the zone you give as a POSIX TZ string
(UTC0, MSK-3).
Into the setup of a machine that says so on its splash screen:
timeout 120
wait Press F2
key f2
wait BootLog in on a Linux console and start a service:
wait login:
type root
key enter
delay 500
wait assword
type hunter2
key enter
wait #
type systemctl start nginx
key enterPick the second entry of a boot menu, as a macro or a runbook:
key down
delay 200
key enterThe same reference lives in the firmware repository as docs/SCRIPTS.md.