====== Prompt user to press key ======

===== Synopsis =====

    prompt [--key <key>] [--timeout <timeout>] [<text>]

===== Examples =====

=== Wait for the user to press a key ===

    prompt

=== Prompt the user to press a key to continue ===

    prompt Press any key to continue

=== Exit script if 'q' is pressed ===

    prompt --key q Press 'q' to quit && exit ||

=== Exit script unless F12 is pressed within 2 seconds ===

    prompt --key 0x197e --timeout 2000 Press F12 to boot from network... || exit

=== Offer user an opportunity to enter the iPXE shell ===

    prompt --key 0x02 --timeout 2000 Press Ctrl-B for the iPXE command line... && shell ||

===== Description =====

Prompt the user to press a key, displaying the specified text and waiting for the specified timeout (in milliseconds).  If no timeout is explicitly specified, or if a zero timeout is specified, then iPXE will wait indefinitely.

The command status will be successful if the specified key was pressed.  If no key was explicitly specified, then the command will be successful if any key was pressed.

The displayed text will be cleared when the user presses a key, or if the timeout expires.

The ''%%--key%%'' option can be specified as a character literal (such as ''q'' or ''@'') or as an extended ASCII character value.  The values for special keys such as ''Ctrl-B'' and ''F12'' are defined in [[http://git.ipxe.org/ipxe.git/blob/HEAD:/src/include/ipxe/keys.h|include/ipxe/keys.h]] within the iPXE source code.  Some useful values are:

^ Key      ^ Keycode   |
| Ctrl-A   | 0x01      |
| Ctrl-B   | 0x02      |
| Ctrl-C   | 0x03      |
| ...                 ||
| Ctrl-Z   | 0x1a      |
| F5       | 0x107e    |
| F6       | 0x127e    |
| F7       | 0x137e    |
| F8       | 0x147e    |
| F9       | 0x157e    |
| F10      | 0x167e    |
| F11      | 0x187e    |
| F12      | 0x197e    |

===== Command status =====

^ Success   | The specified key was pressed within the timeout period      |
^ Failure   | The specified key was not pressed within the timeout period  |

===== See also =====

  * ''[[:cmd:echo]]''
  * iPXE [[:scripting|scripting]] guide
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

To prevent the ''prompt'' command from causing your script to exit, you will almost always want to use the ''||'' operator.  For example, do **not** use a line such as

    prompt --timeout 1000 Press any key to install Linux && goto install

If the user does not press a key, then the ''prompt'' command will fail and will cause your script to exit immediately.  You can avoid this problem by using the ''||'' operator to ensure that the failure of the ''prompt'' command is handled appropriately.  For example:

    prompt --timeout 1000 Press any key to install Linux && goto install || goto no_install

or

    prompt --timeout 1000 Press any key to install Linux && goto install ||

See the iPXE [[:scripting|scripting]] guide for further information on the ''&&'' and ''||'' operators.

When you use an embedded script, you will no longer see the "Press Ctrl-B for the iPXE command line" prompt at startup or if booting fails.  You can generate your own prompt using the ''prompt'' command.  For example:

    #!ipxe
    
    # Give user a chance to enter the shell
    prompt --key 0x02 --timeout 2000 Press Ctrl-B for the iPXE shell... || goto no_shell
    shell
    exit
    
    :no_shell
    # Boot the system
    ...