Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Pipelines
    • Working with Strings
    • Working with Lists
    • Working with Records
    • Working with Tables
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library (Preview)
    • Dataframes
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore

Coloring and Theming in Nu

Many parts of Nushell's interface can have their color customized. All of these can be set in the config.nu configuration file. If you see the # outside of a text value in the config file it means the text after it is commented out.

Table Borders

Table borders are controlled by the $env.config.table.mode setting. It can be changed at run time, or in the config.nu file:

$env.config.table.mode = 'rounded'

The options for $env.config.table.mode can be listed with table --list:

  • ascii_rounded
  • basic_compact
  • basic
  • compact_double
  • compact
  • default
  • dots
  • heavy
  • light
  • markdown
  • none
  • psql
  • reinforced
  • restructured
  • rounded
  • thin
  • with_love

Examples:

$env.config.table.mode = 'rounded'
table --list | first 5
# => ╭───┬────────────────╮
# => │ 0 │ basic          │
# => │ 1 │ compact        │
# => │ 2 │ compact_double │
# => │ 3 │ default        │
# => │ 4 │ heavy          │
# => ╰───┴────────────────╯

$env.config.table.mode = 'psql'
table --list | first 5
# =>  0 | basic
# =>  1 | compact
# =>  2 | compact_double
# =>  3 | default
# =>  4 | heavy

Color Configuration

The color configuration is defined in $env.config.color_config. The current configuration can be printed with:

$env.config.color_config | sort

The color and style-attributes can be declared in multiple alternative formats.

  • r - normal color red's abbreviation
  • rb - normal color red's abbreviation with bold attribute
  • red - normal color red
  • red_bold - normal color red with bold attribute
  • "#ff0000" - "#hex" format foreground color red (quotes are required)
  • { fg: "#ff0000" bg: "#0000ff" attr: b } - "full #hex" format foreground red in "#hex" format with a background of blue in "#hex" format with an attribute of bold abbreviated.
  • {|x| 'yellow' } - closure returning a string with one of the color representations listed above
  • {|x| { fg: "#ff0000" bg: "#0000ff" attr: b } } - closure returning a valid record

Attributes

codemeaning
lblink
bbold
ddimmed
hhidden
iitalic
rreverse
sstrikethrough
uunderline
nnothing
defaults to nothing

Normal Colors and Abbreviations

codename
ggreen
gbgreen_bold
gugreen_underline
gigreen_italic
gdgreen_dimmed
grgreen_reverse
bg_gbg_green
lglight_green
lgblight_green_bold
lgulight_green_underline
lgilight_green_italic
lgdlight_green_dimmed
lgrlight_green_reverse
bg_lgbg_light_green
rred
rbred_bold
rured_underline
rired_italic
rdred_dimmed
rrred_reverse
bg_rbg_red
lrlight_red
lrblight_red_bold
lrulight_red_underline
lrilight_red_italic
lrdlight_red_dimmed
lrrlight_red_reverse
bg_lrbg_light_red
ublue
ubblue_bold
uublue_underline
uiblue_italic
udblue_dimmed
urblue_reverse
bg_ubg_blue
lulight_blue
lublight_blue_bold
luulight_blue_underline
luilight_blue_italic
ludlight_blue_dimmed
lurlight_blue_reverse
bg_lubg_light_blue
bblack
bbblack_bold
bublack_underline
biblack_italic
bdblack_dimmed
brblack_reverse
bg_bbg_black
ligrlight_gray
ligrblight_gray_bold
ligrulight_gray_underline
ligrilight_gray_italic
ligrdlight_gray_dimmed
ligrrlight_gray_reverse
bg_ligrbg_light_gray
yyellow
ybyellow_bold
yuyellow_underline
yiyellow_italic
ydyellow_dimmed
yryellow_reverse
bg_ybg_yellow
lylight_yellow
lyblight_yellow_bold
lyulight_yellow_underline
lyilight_yellow_italic
lydlight_yellow_dimmed
lyrlight_yellow_reverse
bg_lybg_light_yellow
ppurple
pbpurple_bold
pupurple_underline
pipurple_italic
pdpurple_dimmed
prpurple_reverse
bg_pbg_purple
lplight_purple
lpblight_purple_bold
lpulight_purple_underline
lpilight_purple_italic
lpdlight_purple_dimmed
lprlight_purple_reverse
bg_lpbg_light_purple
mmagenta
mbmagenta_bold
mumagenta_underline
mimagenta_italic
mdmagenta_dimmed
mrmagenta_reverse
bg_mbg_magenta
lmlight_magenta
lmblight_magenta_bold
lmulight_magenta_underline
lmilight_magenta_italic
lmdlight_magenta_dimmed
lmrlight_magenta_reverse
bg_lmbg_light_magenta
ccyan
cbcyan_bold
cucyan_underline
cicyan_italic
cdcyan_dimmed
crcyan_reverse
bg_cbg_cyan
lclight_cyan
lcblight_cyan_bold
lculight_cyan_underline
lcilight_cyan_italic
lcdlight_cyan_dimmed
lcrlight_cyan_reverse
bg_lcbg_light_cyan
wwhite
wbwhite_bold
wuwhite_underline
wiwhite_italic
wdwhite_dimmed
wrwhite_reverse
bg_wbg_white
dgrdark_gray
dgrbdark_gray_bold
dgrudark_gray_underline
dgridark_gray_italic
dgrddark_gray_dimmed
dgrrdark_gray_reverse
bg_dgrbg_dark_gray
defdefault
defbdefault_bold
defudefault_underline
defidefault_italic
defddefault_dimmed
defrdefault_reverse
bg_defbg_default

"#hex" Format

The "#hex" format is one way you typically see colors represented. It's simply the # character followed by 6 characters. The first two are for red, the second two are for green, and the third two are for blue. It's important that this string be surrounded in quotes, otherwise Nushell thinks it's a commented out string.

Example: The primary red color is "#ff0000" or "#FF0000". Upper and lower case in letters shouldn't make a difference.

This "#hex" format allows us to specify 24-bit truecolor tones to different parts of Nushell.

Full "#hex" Format

The full "#hex" format is a take on the "#hex" format but allows one to specify the foreground, background, and attributes in one line.

Example: { fg: "#ff0000" bg: "#0000ff" attr: b }

  • foreground of red in "#hex" format
  • background of blue in "#hex" format
  • attribute of bold abbreviated

Closure

Note: Closures are only executed for table output. They do not work in other contexts like for shape_ configurations, when printing a value directly, or as a value in a list.

For example:

$env.config.color_config.filesize = {|x| if $x == 0b { 'dark_gray' } else if $x < 1mb { 'cyan' } else { 'blue' } }
$env.config.color_config.bool = {|x| if $x { 'green' } else { 'light_red' } }
{a:true,b:false,c:0mb,d:0.5mb,e:10mib}

prints

╭───┬───────────╮
│ a │ true      │
│ b │ false     │
│ c │ 0 B       │
│ d │ 488.3 KiB │
│ e │ 10.0 MiB  │
╰───┴───────────╯

with a green true, a light red false, a dark grey 0 B, a cyan 488.3 KiB, and a blue 10.0 MiB.

Primitive Values

Primitive values are things like int and string. Primitive values and shapes can be set with a variety of color symbologies seen above.

This is the current list of primitives. Not all of these are configurable. The configurable ones are marked with *.

primitivedefault colorconfigurable
any
binaryColor::White.normal()*
blockColor::White.normal()*
boolColor::White.normal()*
cellpathColor::White.normal()*
condition
custom
dateColor::White.normal()*
durationColor::White.normal()*
expression
filesizeColor::White.normal()*
floatColor::White.normal()*
glob
import
intColor::White.normal()*
listColor::White.normal()*
nothingColor::White.normal()*
number
operator
path
rangeColor::White.normal()*
recordColor::White.normal()*
signature
stringColor::White.normal()*
table
var
vardecl
variable

Special "primitives" (not really primitives but they exist solely for coloring)

primitivedefault colorconfigurable
leading_trailing_space_bgColor::Rgb(128, 128, 128))*
headerColor::Green.bold()*
emptyColor::Blue.normal()*
row_indexColor::Green.bold()*
hintsColor::DarkGray.normal()*

Here's a small example of changing some of these values.

let config = {
    color_config: {
        separator: purple
        leading_trailing_space_bg: "#ffffff"
        header: gb
        date: wd
        filesize: c
        row_index: cb
        bool: red
        int: green
        duration: blue_bold
        range: purple
        float: red
        string: white
        nothing: red
        binary: red
        cellpath: cyan
        hints: dark_gray
    }
}

Here's another small example using multiple color syntaxes with some comments.

let config = {
    color_config: {
        separator: "#88b719" # this sets only the foreground color like PR #486
        leading_trailing_space_bg: white # this sets only the foreground color in the original style
        header: { # this is like PR #489
            fg: "#B01455", # note, quotes are required on the values with hex colors
            bg: "#ffb900", # note, commas are not required, it could also be all on one line
            attr: bli # note, there are no quotes around this value. it works with or without quotes
        }
        date: "#75507B"
        filesize: "#729fcf"
        row_index: {
            # note, that this is another way to set only the foreground, no need to specify bg and attr
            fg: "#e50914"
        }
    }
}

Shape Values

As mentioned above, shape is a term used to indicate the syntax coloring.

Here's the current list of flat shapes.

shapedefault styleconfigurable
shape_blockfg(Color::Blue).bold()*
shape_boolfg(Color::LightCyan)*
shape_custombold()*
shape_externalfg(Color::Cyan)*
shape_externalargfg(Color::Green).bold()*
shape_filepathfg(Color::Cyan)*
shape_flagfg(Color::Blue).bold()*
shape_floatfg(Color::Purple).bold()*
shape_garbagefg(Color::White).on(Color::Red).bold()*
shape_globpatternfg(Color::Cyan).bold()*
shape_intfg(Color::Purple).bold()*
shape_internalcallfg(Color::Cyan).bold()*
shape_listfg(Color::Cyan).bold()*
shape_literalfg(Color::Blue)*
shape_nothingfg(Color::LightCyan)*
shape_operatorfg(Color::Yellow)*
shape_rangefg(Color::Yellow).bold()*
shape_recordfg(Color::Cyan).bold()*
shape_signaturefg(Color::Green).bold()*
shape_stringfg(Color::Green)*
shape_string_interpolationfg(Color::Cyan).bold()*
shape_tablefg(Color::Blue).bold()*
shape_variablefg(Color::Purple)*

Here's a small example of how to apply color to these items. Anything not specified will receive the default color.

$env.config = {
    color_config: {
        shape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
        shape_bool: green
        shape_int: { fg: "#0000ff" attr: b}
    }
}

Prompt Configuration and Coloring

The Nushell prompt is configurable through these environment variables and config items:

  • PROMPT_COMMAND: Code to execute for setting up the prompt (block)
  • PROMPT_COMMAND_RIGHT: Code to execute for setting up the RIGHT prompt (block) (see oh-my.nu in nu_scripts)
  • PROMPT_INDICATOR = "〉": The indicator printed after the prompt (by default ">"-like Unicode symbol)
  • PROMPT_INDICATOR_VI_INSERT = ": "
  • PROMPT_INDICATOR_VI_NORMAL = "v "
  • PROMPT_MULTILINE_INDICATOR = "::: "
  • render_right_prompt_on_last_line: Bool value to enable or disable the right prompt to be rendered on the last line of the prompt

Example: For a simple prompt one could do this. Note that PROMPT_COMMAND requires a block whereas the others require a string.

$env.PROMPT_COMMAND = { $"(date now | format date '%m/%d/%Y %I:%M:%S%.3f'): (pwd | path basename)" }

If you don't like the default PROMPT_INDICATOR you could change it like this.

$env.PROMPT_INDICATOR = "> "

If you're using starship, you'll most likely want to show the right prompt on the last line of the prompt, just like zsh or fish. You could modify the config.nu file, just set render_right_prompt_on_last_line to true:

config {
    render_right_prompt_on_last_line = true
    ...
}

Coloring of the prompt is controlled by the block in PROMPT_COMMAND where you can write your own custom prompt. We've written a slightly fancy one that has git statuses located in the nu_scripts repo.

Transient Prompt

If you want a different prompt displayed for previously entered commands, you can use Nushell's transient prompt feature. This can be useful if your prompt has lots of information that is unnecessary to show for previous lines (e.g. time and Git status), since you can make it so that previous lines show with a shorter prompt.

Each of the PROMPT_* variables has a corresponding TRANSIENT_PROMPT_* variable to be used for changing that segment when displaying past prompts: TRANSIENT_PROMPT_COMMAND, TRANSIENT_PROMPT_COMMAND_RIGHT, TRANSIENT_PROMPT_INDICATOR, TRANSIENT_PROMPT_INDICATOR_VI_INSERT, TRANSIENT_PROMPT_INDICATOR_VI_NORMAL, TRANSIENT_PROMPT_MULTILINE_INDICATOR. By default, the PROMPT_* variables are used for displaying past prompts.

For example, if you want to make past prompts show up without a left prompt entirely and leave only the indicator, you can use:

$env.TRANSIENT_PROMPT_COMMAND = ""

If you want to go back to the normal left prompt, you'll have to unset TRANSIENT_PROMPT_COMMAND:

hide-env TRANSIENT_PROMPT_COMMAND

LS_COLORS Colors for the ls Command

Nushell will respect and use the LS_COLORS environment variable setting on Mac, Linux, and Windows. This setting allows you to define the coloring of file types when you do a ls. For instance, you can make directories one color, .md Markdown files another color, .toml files yet another color, etc. There are a variety of ways to color and style your file types.

If LS_COLORS is not set, nushell will default to a built-in LS_COLORS setting, based on 8-bit (extended) ANSI colors.

Understanding LS_COLORS

LS_COLORS contains a colon (:) separated list of records that map file types and file names to styling attributes (selector=attributes).

The selector can be a file type specified like di for "directory identifier", or *.nu for files with the .nu file extension.

The attributes are a list of semicolon (;) separated numbers. Note that which attributes and attribute formats are supported depends on the terminal you are using.

  • Style attributes like 0 normal, 1 bold, 3 italic, 5 blink, etc
  • Foreground colors 30-37 and 90-97
  • Background colors 40-47 and 100-107
  • RGB foreground prefixed with 38;2, optionally followed by additional attributes
  • RGB background prefixed with 48;2, optionally followed by additional attributes

For example:

$env.LS_COLORS = "di=1;34:*.nu=3;33;46": Bold directories, italic yellow foreground cyan background *.nu files

$env.LS_COLORS = "di=48;2;200;0;0;5": Red background blinking directories

vivid Themes

For example, you can use the third-party tool vivid, which runs on multiple platforms, has many themes defined, and generates a LS_COLORS configuration from it.

After downloading and extracting the binary, you can use it with:

$env.LS_COLORS = (vivid generate molokai)

or with an alternative theme:

$env.LS_COLORS = (vivid generate ayu)

You can put this command into your Nushell configuration for it to become the default coloring.

Theming

Theming combines all the coloring above. Here's a quick example of one we put together quickly to demonstrate the ability to theme. This is a spin on the base16 themes that we see so widespread on the web.

The key to making theming work is to make sure you specify all themes and colors you're going to use in the config.nu file before you declare the let config = line.

# let's define some colors

let base00 = "#181818" # Default Background
let base01 = "#282828" # Lighter Background (Used for status bars, line number and folding marks)
let base02 = "#383838" # Selection Background
let base03 = "#585858" # Comments, Invisibles, Line Highlighting
let base04 = "#b8b8b8" # Dark Foreground (Used for status bars)
let base05 = "#d8d8d8" # Default Foreground, Caret, Delimiters, Operators
let base06 = "#e8e8e8" # Light Foreground (Not often used)
let base07 = "#f8f8f8" # Light Background (Not often used)
let base08 = "#ab4642" # Variables, XML Tags, Markup Link Text, Markup Lists, Diff Deleted
let base09 = "#dc9656" # Integers, Boolean, Constants, XML Attributes, Markup Link Url
let base0a = "#f7ca88" # Classes, Markup Bold, Search Text Background
let base0b = "#a1b56c" # Strings, Inherited Class, Markup Code, Diff Inserted
let base0c = "#86c1b9" # Support, Regular Expressions, Escape Characters, Markup Quotes
let base0d = "#7cafc2" # Functions, Methods, Attribute IDs, Headings
let base0e = "#ba8baf" # Keywords, Storage, Selector, Markup Italic, Diff Changed
let base0f = "#a16946" # Deprecated, Opening/Closing Embedded Language Tags, e.g. <?php ?>

# we're creating a theme here that uses the colors we defined above.

let base16_theme = {
    separator: $base03
    leading_trailing_space_bg: $base04
    header: $base0b
    date: $base0e
    filesize: $base0d
    row_index: $base0c
    bool: $base08
    int: $base0b
    duration: $base08
    range: $base08
    float: $base08
    string: $base04
    nothing: $base08
    binary: $base08
    cellpath: $base08
    hints: dark_gray

    # shape_garbage: { fg: $base07 bg: $base08 attr: b} # base16 white on red
    # but i like the regular white on red for parse errors
    shape_garbage: { fg: "#FFFFFF" bg: "#FF0000" attr: b}
    shape_bool: $base0d
    shape_int: { fg: $base0e attr: b}
    shape_float: { fg: $base0e attr: b}
    shape_range: { fg: $base0a attr: b}
    shape_internalcall: { fg: $base0c attr: b}
    shape_external: $base0c
    shape_externalarg: { fg: $base0b attr: b}
    shape_literal: $base0d
    shape_operator: $base0a
    shape_signature: { fg: $base0b attr: b}
    shape_string: $base0b
    shape_filepath: $base0d
    shape_globpattern: { fg: $base0d attr: b}
    shape_variable: $base0e
    shape_flag: { fg: $base0d attr: b}
    shape_custom: {attr: b}
}

# now let's apply our regular config settings but also apply the "color_config:" theme that we specified above.

let config = {
  filesize_metric: true
  table_mode: rounded # basic, compact, compact_double, light, thin, with_love, rounded, reinforced, heavy, none, other
  use_ls_colors: true
  color_config: $base16_theme # <-- this is the theme
  use_grid_icons: true
  footer_mode: always #always, never, number_of_rows, auto
  animate_prompt: false
  float_precision: 2
  use_ansi_coloring: true
  filesize_format: "b" # b, kb, kib, mb, mib, gb, gib, tb, tib, pb, pib, eb, eib, auto
  edit_mode: emacs # vi
  max_history_size: 10000
  log_level: error
}

if you want to go full-tilt on theming, you'll want to theme all the items I mentioned at the very beginning, including LS_COLORS, and the prompt. Good luck!

Working on Light Background Terminal

Nushell's standard library contains a config module with default light and dark themes. If you are working on a light background terminal, you can apply the light theme easily.

# in $nu.config-path
use config light-theme   # add this line to load the theme into scope

$env.config = {
  # ...
  color_config: (light_theme)   # if you want a light theme, replace `$dark_theme` to `$light_theme`
  # ...
}

You can also load the dark theme.

# in $nu.config-path
use config dark-theme

$env.config = {
  # ...
  color_config: (dark_theme)
  # ...
}

Accessibility

It's often desired to have the minimum amount of decorations when using a screen reader. In those cases, it's possible to disable borders and other decorations for both table and errors with the following options:

# in $nu.config-path
$env.config = {
  ...
  table: {
   ...
    mode: "none"
   ...
  }
  error_style: "plain"
  ...
}

Line Editor Menus (completion, history, help…)

Reedline (Nu’s line editor) style is not using the color_config key. Instead, each menu has its own style to be configured separately. See the section dedicated to Reedline’s menus configuration to learn more on this.

Edit this page on GitHub
Contributors: fdncred, Luca Trevisani, Reilly Wood, rgwood, Vishal Sodani, Kai Welke, chtenb, Justin Ma, Reilly Tucker Siemens, WindSoilder, Jakub Žádník, Zhora Trush, nibon7, Hofer-Julian, Máté FARKAS, Stefan Holderbach, Mate Farkas, hanjunghyuk, amtoine, Joaquín Triñanes, ysthakur, Benoît Cortier, Marika Chlebowska, 0x4D5352, NotTheDr01ds, joshuanussbaum, Jan Klass, Bahex, Antonio Caceres
Prev
Externs
Next
Hooks