====== Define colour ======

===== Synopsis =====

    colour [--basic <basic ANSI colour>] [--rgb <RGB value>] <colour>

===== Examples =====

=== Redefine colour 7 as ANSI red ===

    colour --basic 1 7

=== Redefine colour 7 as ANSI red and use it as the default foreground colour ===

    colour --basic 1 7
    cpair --foreground 7 0

=== Redefine colour 4 as midnight blue ===

    colour --rgb 0x191970 4

===== Description =====

Define the specified colour index (in the range ''0'' to ''7'') to use the specified basic ANSI colour (in the range ''0'' to ''7'') and the specified 24-bit RGB colour (in the range ''0x000000'' to ''0xffffff'').  The basic ANSI colour will be used on consoles which do not support arbitrary RGB colours.

If the RGB value is omitted, then only the basic ANSI colour will be used.  If the basic ANSI colour is omitted, then the default colour (white foreground, black or transparent background) will be used.

The default colour definitions are:

^ Colour index  ^ Basic ANSI colour    ^
| 0             | 0 (black)            |
| 1             | 1 (red)              |
| 2             | 2 (green)            |
| 3             | 3 (yellow)           |
| 4             | 15 (blue or transparent)((ANSI colours are in the range 0 to 7 inclusive.  The special value 15 is used to indicate the "magic" colour, which will be transparent on consoles which support a transparent background but blue on consoles which do not support transparency.  This allows iPXE menus (and other user interfaces) to automatically become semi-transparent when a background picture is present.))  |
| 5             | 5 (magenta)          |
| 6             | 6 (cyan)             |
| 7             | 7 (white)            |
| 9             | 9 (default)((ANSI colour 9 indicates "default": this will be white when used as a foreground colour and black (or transparent) when used as a background colour.  Colour index 9 cannot be redefined using the ''colour'' command.))  |

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

^ Success   | The colour was successfully defined          |
^ Failure   | The colour was not successfully defined      |

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

  * ''[[:cmd:cpair]]''
  * ''[[:cmd:console]]''
  * [[:console|Console configuration]] in iPXE
  * [[:cmd|List of all iPXE commands]]

===== Build options =====

This command is available only when the build option ''[[:buildcfg:CONSOLE_CMD]]'' is enabled.

===== Notes =====

To change the default foreground and background colour used by iPXE, you must use the ''[[:cmd:cpair]]'' command to redefine colour pair 0 to use your chosen colours.

Not all consoles support full RGB colours.  You can use the basic ANSI colour as a fallback.  For example, to define colour 6 as turqouise, falling back to cyan if RGB colours are not available:

    colour --basic 6 --rgb 0x40e0d0 6