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
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • 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
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • 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
    • Coming from PowerShell
    • 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
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

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
  • double
  • frameless
  • heavy
  • light
  • markdown
  • none
  • psql
  • reinforced
  • restructured
  • rounded
  • single
  • thin
  • with_love

The names ignore case, so 'PSQL' works too. default is another name for rounded, so after you assign 'default', the setting reads back as rounded.

To draw one table in a different mode, pass it to table --theme (-t) and leave the setting alone. To try a mode without changing your configuration, start Nushell with nu --table-mode <mode> (-m). The flag overrides the mode from config.nu, but $env.config.table.mode keeps the configured value.

[[a b]; [1 2]] | table --theme markdown
# => | # | a | b |
# => |---|---|---|
# => | 0 | 1 | 2 |

Examples:

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

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

$env.config.table.mode = 'rounded' # back to the default

Other table display settings

$env.config.footer_mode decides when a table repeats its column names below the last row. Only tables with a header row get a footer, such as a list of records. A plain list never does. The setting takes "always", "never", "auto", or a number of rows (default 25), as described under footer_mode. With a number, a table with at least that many rows gets a footer:

$env.config.footer_mode = 3
[[name]; [a] [b] [c]]
# => ╭───┬──────╮
# => │ # │ name │
# => ├───┼──────┤
# => │ 0 │ a    │
# => │ 1 │ b    │
# => │ 2 │ c    │
# => ├───┼──────┤
# => │ # │ name │
# => ╰───┴──────╯

$env.config.float_precision sets how many decimal places a float gets when Nushell draws it inside a table, list, or record. The default is 2. The float itself keeps its full precision, and a float printed on its own or converted to a string isn't rounded.

$env.config.float_precision = 4
[3.14159 2.0]
# => ╭───┬────────╮
# => │ 0 │ 3.1416 │
# => │ 1 │ 2.0000 │
# => ╰───┴────────╯
3.14159
# => 3.14159
3.14159 | into string
# => 3.14159

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

Color names are case-sensitive. red works, but Red and RED don't. Nushell doesn't report a name it doesn't know, and draws the text in the terminal's default color instead.

A string that starts with { is read as a JSON style record, so '{"fg": "red", "attr": "u"}' works like the record { fg: red attr: u }. It has to be valid JSON, with every key and value in double quotes.

Attributes

codename
lblink
bbold
ddimmed
hhidden
iitalic
rreverse
sstrike, strikethrough
uunderline
nnormal (no attribute)
defaults to nothing

attr takes codes or names, in any case. Codes can run together, so attr: bi is bold italic, and names go in one string separated by spaces, as in attr: 'bold italic'. If any part of attr isn't a code or a name, or the string contains a comma, Nushell ignores the whole style, fg and bg included, and draws the value unstyled.

Normal Colors and Abbreviations

These names set the foreground color. For a background color, use the record format, such as { bg: red }. The bg_* names that the ansi command accepts, such as bg_red, have no effect in color_config. Every color except default also has a _blink and a _strike form.

codename
ggreen
gbgreen_bold
gugreen_underline
gigreen_italic
gdgreen_dimmed
grgreen_reverse
gblgreen_blink
gstgreen_strike
lglight_green
lgblight_green_bold
lgulight_green_underline
lgilight_green_italic
lgdlight_green_dimmed
lgrlight_green_reverse
lgbllight_green_blink
lgstlight_green_strike
rred
rbred_bold
rured_underline
rired_italic
rdred_dimmed
rrred_reverse
rblred_blink
rstred_strike
lrlight_red
lrblight_red_bold
lrulight_red_underline
lrilight_red_italic
lrdlight_red_dimmed
lrrlight_red_reverse
lrbllight_red_blink
lrstlight_red_strike
ublue
ubblue_bold
uublue_underline
uiblue_italic
udblue_dimmed
urblue_reverse
ublblue_blink
ustblue_strike
lulight_blue
lublight_blue_bold
luulight_blue_underline
luilight_blue_italic
ludlight_blue_dimmed
lurlight_blue_reverse
lubllight_blue_blink
lustlight_blue_strike
bblack
bbblack_bold
bublack_underline
biblack_italic
bdblack_dimmed
brblack_reverse
bblblack_blink
bstblack_strike
ligrlight_gray
ligrblight_gray_bold
ligrulight_gray_underline
ligrilight_gray_italic
ligrdlight_gray_dimmed
ligrrlight_gray_reverse
ligrbllight_gray_blink
ligrstlight_gray_strike
yyellow
ybyellow_bold
yuyellow_underline
yiyellow_italic
ydyellow_dimmed
yryellow_reverse
yblyellow_blink
ystyellow_strike
lylight_yellow
lyblight_yellow_bold
lyulight_yellow_underline
lyilight_yellow_italic
lydlight_yellow_dimmed
lyrlight_yellow_reverse
lybllight_yellow_blink
lystlight_yellow_strike
ppurple
pbpurple_bold
pupurple_underline
pipurple_italic
pdpurple_dimmed
prpurple_reverse
pblpurple_blink
pstpurple_strike
lplight_purple
lpblight_purple_bold
lpulight_purple_underline
lpilight_purple_italic
lpdlight_purple_dimmed
lprlight_purple_reverse
lpbllight_purple_blink
lpstlight_purple_strike
mmagenta
mbmagenta_bold
mumagenta_underline
mimagenta_italic
mdmagenta_dimmed
mrmagenta_reverse
mblmagenta_blink
mstmagenta_strike
lmlight_magenta
lmblight_magenta_bold
lmulight_magenta_underline
lmilight_magenta_italic
lmdlight_magenta_dimmed
lmrlight_magenta_reverse
lmbllight_magenta_blink
lmstlight_magenta_strike
ccyan
cbcyan_bold
cucyan_underline
cicyan_italic
cdcyan_dimmed
crcyan_reverse
cblcyan_blink
cstcyan_strike
lclight_cyan
lcblight_cyan_bold
lculight_cyan_underline
lcilight_cyan_italic
lcdlight_cyan_dimmed
lcrlight_cyan_reverse
lcbllight_cyan_blink
lcstlight_cyan_strike
wwhite
wbwhite_bold
wuwhite_underline
wiwhite_italic
wdwhite_dimmed
wrwhite_reverse
wblwhite_blink
wstwhite_strike
dgrdark_gray
dgrbdark_gray_bold
dgrudark_gray_underline
dgridark_gray_italic
dgrddark_gray_dimmed
dgrrdark_gray_reverse
dgrbldark_gray_blink
dgrstdark_gray_strike
defdefault
defbdefault_bold
defudefault_underline
defidefault_italic
defddefault_dimmed
defrdefault_reverse

color_config also accepts the 256 xterm colors that ansi --list shows with an xterm_ prefix, such as xterm_navy or xterm_grey42. Use the full xterm_ name. These colors have no _bold or other forms, so add attributes with a record, such as { fg: xterm_navy attr: b }.

"#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.

Only the six-digit form works, as a plain string or as fg or bg in a record. The three-digit shorthand that CSS allows, such as "#f00", gives no color.

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

Nushell runs these closures only when it draws a table, list, or record. A value printed on its own, such as a bare 3, isn't styled at all, and the shape_* keys don't accept closures.

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}
# => ╭───┬──────────╮
# => │ a │ true     │
# => │ b │ false    │
# => │ c │ 0 B      │
# => │ d │ 500.0 kB │
# => │ e │ 10.4 MB  │
# => ╰───┴──────────╯

The table shows a green true, a light red false, a dark grey 0 B, a cyan 500.0 kB, and a blue 10.4 MB.

The closure gets the value both as its parameter and as $in, so {|| if $in { 'green' } else { 'light_red' } } works the same as the bool closure above. It has to return a color string or a style record. Any other result, such as a number, leaves the value unstyled. If the closure raises an error, Nushell prints the error once for each value it was styling and draws those values unstyled.

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.

These keys style values of each type when Nushell draws them in a table, list, or record.

keydefault style
binarydefault
blockdefault
boollight_cyan
cell-pathdefault
customnot set
datetimepurple
durationdefault
filesizecyan
floatdefault
globcyan_bold
intdefault
listdefault
nothingdefault
rangedefault
recorddefault
semvercyan_bold
semver-rangecyan_bold
stringdefault

A few of these keys behave differently from the rest:

  • list and record style the [list 2 items] and {record 1 field} summaries that a table shows in place of a nested value. list also styles the [table 1 row] summary of a nested table.
  • block is reserved and changes nothing.

Other type names, such as any, number, or table, aren't color_config keys, and setting them has no effect.

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

keydefault stylestyles
leading_trailing_space_bg{ attr: n }spaces at the start and end of strings in tables
headergreen_boldcolumn headers, the # heading, and the keys of a record
emptybluethe placeholder for a missing cell
row_indexgreen_boldthe index numbers in the # column
separatordefaultthe borders of tables, lists, and records
hintsdark_grayinline hints in the line editor
status_linethe hints stylethe status line under the prompt
status_line_errorredan error shown in the status line
search_result{ bg: red, fg: default }the matches that find highlights
selection{ attr: r }text selected in Vi visual mode or Helix mode
selection_cursor{ attr: n }the character under the cursor inside a selection
binary_null_chargrey4200 bytes in the binary hex view
binary_printablecyan_boldprintable ASCII bytes in the hex view
binary_whitespacegreen_boldASCII whitespace bytes in the hex view
binary_ascii_otherpurple_boldother ASCII bytes, such as control characters
binary_non_asciiyellow_boldbytes above 0x7f

leading_trailing_space_bg needs a background color, such as { bg: dark_gray }, because a foreground color has nothing to draw on a space. The default { attr: n } turns the highlight off.

empty styles the symbol that $env.config.table.missing_value_symbol sets for a cell a row doesn't have. The default symbol is an emoji, and many terminals draw emoji in their own colors, so empty may not change anything until you pick a plain-text symbol.

The binary_* keys color the hex view that Nushell shows for a binary value printed on its own, such as 0x[41 00 20 ff].

Here's a small example of changing some of these values. The color names are quoted because Nushell treats a bare word on the right side of = as a command name, so = purple is a parse error.

$env.config.color_config.separator = 'purple'
$env.config.color_config.leading_trailing_space_bg = { bg: "#ffffff" }
$env.config.color_config.header = 'gb'
$env.config.color_config.datetime = 'wd'
$env.config.color_config.filesize = 'c'
$env.config.color_config.row_index = 'cb'
$env.config.color_config.bool = 'red'
$env.config.color_config.int = 'green'
$env.config.color_config.duration = 'blue_bold'
$env.config.color_config.range = 'purple'
$env.config.color_config.float = 'red'
$env.config.color_config.string = 'white'
$env.config.color_config.nothing = 'red'
$env.config.color_config.binary = 'red'
$env.config.color_config.cell-path = 'cyan'
$env.config.color_config.hints = 'dark_gray'

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

$env.config.color_config.separator = "#88b719" # this sets only the foreground color like PR #486
$env.config.color_config.leading_trailing_space_bg = { bg: 'white' } # spaces have no foreground, so set a background
$env.config.color_config.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
}
$env.config.color_config.datetime = "#75507B"
$env.config.color_config.filesize = "#729fcf"
$env.config.color_config.row_index = {
    # note, that this is another way to set only the foreground, no need to specify bg and attr
    fg: "#e50914"
}

Keys for the banner and for theme scripts

Three more keys color the welcome banner: banner_foreground for its text (default attr_normal), and banner_highlight1 (default green) and banner_highlight2 (default purple) for the highlighted words. They aren't in the default color_config, and the banner uses those defaults when they're missing. The banner command passes them to ansi, so they take what ansi takes: its names, such as attr_normal or green, "#hex" strings, and records. Short forms that only color_config knows, such as gbl, make banner fail with an "Unknown ansi code" error.

foreground, background, and cursor are also accepted, but Nushell never reads them. They're there for scripts that set the terminal's own colors, such as the theme commands in nu_scripts. None of the three is set by default.

Shape Values

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

Here's the current list of flat shapes.

shapedefault stylecolors
shape_binarypurple_boldbinary literals such as 0x[ff]
shape_blockblue_boldthe braces of a block, as in if true { }, and the parentheses of a subexpression
shape_boollight_cyantrue and false
shape_closuregreen_boldthe braces and parameters of a closure
shape_datetimecyan_bolddatetime literals such as 2020-01-01
shape_directorycyanarguments that must be a directory, such as foo in cd foo
shape_externalcyana command that Nushell will run as an external command
shape_external_resolvedlight_yellow_boldan external command found in PATH, when $env.config.highlight_resolved_externals is true
shape_externalarggreen_boldthe arguments of an external command
shape_filepathcyanfile path arguments, such as out.txt in save out.txt
shape_flagblue_boldflags such as --all and -a
shape_floatpurple_boldfloat literals
shape_garbage{ fg: default, bg: red, attr: b }a token that doesn't parse where it stands, such as abc in sleep abc or + in 1 +
shape_glob_interpolationcyan_bolddeprecated
shape_globpatterncyan_boldglob arguments, such as *.txt in ls *.txt
shape_intpurple_boldinteger literals
shape_internalcallcyan_boldthe names of Nushell commands
shape_keywordcyan_boldkeywords inside a command's syntax, such as else, catch, and the in of for x in
shape_listcyan_boldthe brackets of a list literal
shape_literalbluenot used
shape_match_patterngreenthe patterns of a match arm
shape_matching_bracketsdefault_underlinethe bracket that pairs with the one under the cursor, on top of its usual style
shape_nothinglight_cyannull
shape_operatoryellowoperators such as + and ==, and the .. of a range
shape_pipepurple_boldthe pipe symbol
shape_raw_stringlight_purpleraw strings such as r#'text'#
shape_recordcyan_boldthe braces and colons of a record literal
shape_redirectionpurple_boldredirections such as o> and e>
shape_signaturegreen_boldthe parameter list of a def
shape_stringgreenstrings, including bare words that Nushell reads as strings
shape_string_interpolationcyan_boldthe $" and " around an interpolated string
shape_tableblue_boldthe brackets and ; of a table literal
shape_variablepurplevariables such as $env
shape_vardeclpurplethe name a variable gets when it's declared, such as x in let x = 1

A shape key that's missing, or set to something other than a string or a record, falls back to its default style.

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

$env.config.color_config.shape_garbage = { fg: "#FFFFFF" bg: "#FF0000" attr: b}
$env.config.color_config.shape_bool = 'green'
$env.config.color_config.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 in Emacs mode
  • PROMPT_INDICATOR_VI_INSERT = ": ": The indicator in Vi insert mode (and Helix insert mode)
  • PROMPT_INDICATOR_VI_NORMAL = "> ": The indicator in Vi normal and visual mode (and Helix normal and select mode)
  • 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. Each PROMPT_* variable takes either a string or a closure that returns one, and Nushell runs the closure every time it draws the prompt.

$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:

$env.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.

What the built-in LS_COLORS contains

The built-in setting has close to 700 entries. Most of them match file extensions or file names, and they fall into these groups. The numbers after 38;5; and 48;5; are 256-color palette indexes for the foreground and background.

entriesstylelooks like
di (directories)0;38;5;81light blue
ex (executables), and files such as *.exe, *.dll, *.so1;38;5;203bold red
ln (symbolic links)0;38;5;203red
or and mi (broken links), do (doors), so (sockets)0;38;5;16;48;5;203black on red
pi (named pipes)0;38;5;16;48;5;81black on light blue
bd (block devices)0;38;5;81;48;5;236light blue on dark grey
cd (character devices)0;38;5;203;48;5;236red on dark grey
source code, such as *.rs, *.py, *.nu, *.sh0;38;5;48green
configuration and build files, such as *.toml, *.json, Makefile0;38;5;149yellow-green
text and markup, such as *.md, *.txt, *.html0;38;5;185yellow
documents, such as *.pdf, *.csv, *.docx0;38;5;186pale yellow
images, audio, and video, such as *.png, *.mp30;38;5;208orange
archives, such as *.zip, *.gz4;38;5;203underlined red
build output and temporary files, such as *.o, *.log, *~0;38;5;243grey
README, CHANGELOG, and similar files0;38;5;16;48;5;186black on pale yellow
LICENSE, COPYING, and similar files0;38;5;249light grey
TODO1bold
fi (regular files) and anything not listed0no color

To stop ls output from using LS_COLORS, built-in or not, set $env.config.ls.use_ls_colors = false. File names then get the color_config.string style like any other string, and they lose the clickable links that ls adds when shell_integration.osc8 is on. The setting defaults to true.

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 define all themes and colors you're going to use in the config.nu file before you assign them to $env.config.color_config.

# 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: { bg: $base04 }
    header: $base0b
    datetime: $base0e
    filesize: $base0d
    row_index: $base0c
    bool: $base08
    int: $base0b
    duration: $base08
    range: $base08
    float: $base08
    string: $base04
    nothing: $base08
    binary: $base08
    cell-path: $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.

$env.config.color_config = $base16_theme # <-- this is the theme
$env.config.edit_mode = 'emacs' # emacs, vi, helix
$env.config.filesize.unit = 'metric'
$env.config.float_precision = 2
$env.config.footer_mode = 'always' # always, never, auto, or a number of rows
$env.config.ls.use_ls_colors = true
$env.config.table.mode = 'rounded' # ascii_rounded, basic, basic_compact, compact, compact_double, default, dots, double, frameless, heavy, light, markdown, none, psql, reinforced, restructured, rounded, single, thin, with_love
$env.config.use_ansi_coloring = 'auto' # auto, true, false

Assigning a record to $env.config.color_config replaces the whole map. Keys the theme leaves out disappear from $env.config.color_config, along with any value you gave them earlier, and Nushell draws those items in their built-in default style:

$env.config.color_config = { header: red }
$env.config.color_config | columns
# => ╭───┬────────╮
# => │ 0 │ header │
# => ╰───┴────────╯

After this, a bool in a table is still light cyan, its built-in default. Code that reads a key directly, such as ansi $env.config.color_config.shape_external, fails with "Cannot find column" once the key is gone, so read keys a theme might leave out with ?, as in $env.config.color_config.shape_external?. To change only a few colors, set those keys one at a time ($env.config.color_config.header = 'red') instead of assigning a record.

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 std/config light-theme   # add this line to load the theme into scope

$env.config.color_config = (light-theme)

You can also load the dark theme.

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

$env.config.color_config = (dark-theme)

Both commands return a record you can inspect or change before assigning it. dark-theme looks like the built-in default theme except for search_result and shape_garbage, which use white text where the defaults use the terminal's default color. light-theme draws most values (int, string, float, duration, and others) and the table borders in dark_gray, so they stay readable on a light background.

Neither theme sets glob, semver, semver-range, selection, selection_cursor, or status_line_error, so after you assign one, those items get their built-in default style.

Turning colors on and off

$env.config.use_ansi_coloring decides whether Nushell's own output, such as tables, help text, and error messages, uses color. It takes three values:

  • "auto", the default, decides from the environment, as described below.
  • true always uses color, and false never does. The strings "true" and "false" work too. With either value, Nushell ignores the environment variables below.

In "auto" mode, Nushell goes through these checks in order and stops at the first one that applies:

  1. If FORCE_COLOR is true, use color.
  2. If NO_COLOR is true, don't use color.
  3. If CLICOLOR is set, use color when it's true and don't when it's false.
  4. If TERM is dumb, don't use color.
  5. Otherwise, use color only when standard output is a terminal.

Nushell reads each of these variables as a boolean. An empty value, 0, and false count as false, and anything else, including no, counts as true. So NO_COLOR=0 doesn't turn colors off, although some other programs treat any non-empty NO_COLOR as a request for no color. The variable names match in any case, so force_color works as well, but the value of TERM has to be lowercase dumb.

config use-colors returns the result of this check, which is handy in scripts that build their own colored output:

$env.config.use_ansi_coloring = false
config use-colors
# => false

The setting doesn't affect the ansi command. ansi red returns the escape code for red even when use_ansi_coloring is false.

Gradient text

ansi gradient colors a string one character at a time, shading from one color to another. --fgstart and --fgend set the foreground color at the two ends of the string, and --bgstart and --bgend do the same for the background. You need at least one of these flags, or one of the named gradients described below, otherwise the command fails with a "Missing parameter" error. If you give a start color without an end color, or the other way around, the missing one is black.

Write each color as 0x followed by six hex digits, such as 0x40c9ff. Any other form, including #40c9ff, quietly turns into black. In this example, str replace makes the escape codes visible:

'abcd' | ansi gradient --fgstart '0xff0000' --fgend '0x0000ff' | str replace --all (ansi escape) '\e'
# => \e[38;2;255;0;0ma\e[38;2;191;0;63mb\e[38;2;127;0;127mc\e[38;2;63;0;191md\e[0m

--fgnamed and --bgnamed take the name of a built-in gradient instead of two colors, such as rainbow or forest, in any case. ansi gradient --list returns a table with each name and a sample text. A named gradient can't be mixed with a start or end color for the same layer, but a named foreground works with a two-color background, and the other way around.

The input can be a string or a list of strings. For a record or a table, pass cell paths to choose which strings get the gradient, as in ansi gradient --fgstart '0xff0000' name. Without cell paths, a record or table input is an error, because every value has to be a string.

ansi gradient treats its input as plain characters. Escape codes already in the string get colored too, one character at a time, which breaks them and prints parts of them, such as [31m, as text. Remove them first with ansi strip:

$"(ansi red)ab(ansi reset)" | ansi strip | ansi gradient --fgstart '0xffffff'

The gradient also counts Unicode characters (code points), not screen columns. A double-width character such as 日 takes one step like any other. A character built from several code points, such as an e followed by a combining accent, gets a color code between its parts.

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"
$env.config.error_style = "plain"

Line Editor Menus (completion, history, help…)

Reedline (Nu’s line editor) menus don't use 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.

The line editor does use a few color_config keys: hints styles the inline hints, selection styles text selected in Vi visual mode or Helix mode, and selection_cursor styles the character under the cursor inside a selection. status_line styles the status line under the prompt, and status_line_error styles an error shown there. The shape_* keys above style the syntax highlighting of the command line.

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, Evgeni Chasnovski, Axlefublr, Giulio Malventi, Richard Levitte, Ethan Hawksley
Prev
Externs
Next
Hooks