Settings and keybindings

Press Mod + , to open Settings. Changes are saved immediately and normally take effect without restarting Newt.

The Preferences tab holds the general options: interface, file operations, hot paths, Go to File, archives, the program search path, terminal, editor, viewer, and background enrichers. The other tabs hold keybindings, user commands, and file associations. The search field filters options by name, description, or key (such as behavior.history_retention), and also filters the Keybindings and Associations tabs. Reset returns a setting to its default.

Configuration files

Newt stores its configuration in the operating system’s application configuration directory:

Platform	Configuration directory
macOS	`~/Library/Application Support/org.newt-fm.newt/`
Linux	`$XDG_CONFIG_HOME/org.newt-fm.newt/`, or `~/.config/org.newt-fm.newt/` when `XDG_CONFIG_HOME` is unset
Windows	`%APPDATA%\org.newt-fm.newt\`

The main configuration file is settings.toml in this directory. To use a different directory, start Newt with --config-dir <PATH>; settings, saved connections, and state files all move with it.

To open the file, use Show in pane or Open in external editor in the Settings footer, or Open Settings File in Editor in the Command Palette. Either footer button creates a commented starter file if none exists. In a remote session, Show in pane needs access to this host. External changes are picked up automatically.

If settings.toml contains mistakes, Newt skips only the settings it cannot use, such as a value of the wrong type or out of range, and lists the problems at the top of Settings and in a notice over the main window. A file that is not valid TOML is ignored as a whole. A file that exists but cannot be read is never overwritten; changing a setting reports the error instead.

Newt also writes state.json (interface state such as column widths, zoom, and recent connections) and sessions.json (pane locations and window geometry) in this directory. These are not meant to be edited by hand.

Common settings

[appearance]
folders_first = true
natural_sort = false        # numbers in names sort by value (IMG_2 before IMG_10)
show_command_bar = true
show_pane_header = true
show_pane_status = true
density = "comfortable"     # compact (20px rows), comfortable (22px), or spacious (24px)
theme = "system"            # system, light, or dark
columns = ["name", "size", "modified_date", "modified_time", "user", "group", "mode", "attributes"]
si_size_prefixes = false    # use prefixed values in the Size column
size_units = "decimal"      # decimal (kB, MB) or binary (KiB, MiB)
locale = ""                 # BCP-47 tag; empty uses the system regional format
date_format = ""            # empty uses the resolved locale's layout
time_format = ""

[behavior]
confirm_delete = true
confirm_close = true        # ask before closing a window with terminals or operations
delete_to_trash = true
keep_terminal_open = true
keep_finished_operations = false
notify_on_prompt = true     # notify when an operation needs input while its window is in the background
quick_search = true
allow_remote_host_access = false # remote sessions may be given access to this host
default_sort = { key = "name", ascending = true } # name, extension, size, modified, accessed, or created
history_retention = 200     # 0 means unlimited
shell_integration = true
restore_locations = "all"  # all, local (local/elevated/WSL), or none
new_window_location = "inherit" # inherit, restore, or default (home)
restore_window_geometry = true
open_packages = false       # macOS: Enter opens app bundles and other packages

[enrichers]
git_status = true

[quick_open]                # Go to File
gitignore = true            # leave out what .gitignore files ignore
follow_symlinks = false
exclude = []                # name globs, for example ["node_modules", "*.pyc"]
limit = 200000              # entries looked at before the search stops
skip_packages = false       # macOS: find apps and other packages, but don't look inside them

[archives]
default_format = "tar_zst" # zip, seven_z, tar, tar_gz, tar_xz, or tar_zst; zip by default on Windows
preserve_symlinks = true
zip_level = 6              # 0-9; 0 stores entries
sevenz_level = 6           # 0-9; 0 stores entries
gzip_level = 6             # 0-9
xz_level = 6               # 0-9
zstd_level = 3             # 1-22

[terminal]
font_family = 'Menlo, Monaco, "Courier New", monospace' # first installed font is used
font_size = 12              # 6-72
scrollback = 1000           # lines kept above the screen (0-1,000,000)

[editor]
word_wrap = false

[viewer]
image_background = "checkerboard" # checkerboard, dark, or light
alternate_mode = "dissect"  # what F3 switches to in the viewer: dissect (Structure) or hex

columns sets both which columns are shown and their order; it is easier to manage from Settings or the file-list header. Columns a filesystem cannot provide, such as User, Group, and Mode on Windows, are hidden there without being removed from the list.

Related settings are described on their own pages: [quick_open] under Go to File, open_packages and [[association]] under File associations, and [terminal] under Terminal and shell.

Program search path

An application started from the desktop does not inherit your shell’s PATH, so Newt also searches environment.extra_path, after PATH, for the programs it runs itself: ssh, docker, podman, kubectl, and git. A leading ~ is your home directory. Terminals and user commands do not use this list. The defaults are:

Platform	Default `extra_path`
macOS	`/opt/homebrew/bin`, `/usr/local/bin`
Linux	`~/.local/bin`, `/snap/bin`, `/var/lib/flatpak/exports/bin`
Windows	none

Numbers, dates, and sizes

Newt formats numbers, dates, and times with appearance.locale, a BCP-47 tag such as de-DE, or with the operating system’s regional format when it is empty. On Windows the regional format can differ from the display language. Custom date_format and time_format values use strftime specifiers (%Y, %y, %m, %d, %e, %j, %b, %B, %a, %A, %H, %I, %M, %S, %p, and %%), such as "%Y-%m-%d" and "%H:%M"; the locale still supplies month and weekday names.

The Size column shows exact byte counts unless si_size_prefixes is enabled. size_units chooses powers of 1000 (kB, GB) or 1024 (KiB, GiB) for prefixed sizes everywhere Newt shows them, including free space, Properties, and operation progress.

Change a keybinding

The Keybindings tab lists built-in, viewer, editor, and user commands. Edit a row, record or remove keys, then save. A built-in command can have several shortcuts; the first is the one shown in menus and the command bar. A user command has one shortcut, stored as key on its [[command]] entry. Escape cancels recording and Tab moves to the next control, so neither can be recorded. Reset restores the default set.

A key already used by another command in the same context blocks Save until you choose Override; the same key in different contexts is not a conflict. Outside edit mode, ⚠ marks a binding another command also uses, and a dot marks a command whose keys differ from its defaults.

Bindings can also be added to settings.toml, one [[bind]] entry per key; several entries may target the same command (to find a command’s ID, search by ID on the Keybindings tab or run newt cmd in Newt’s terminal):

[[bind]]
key = "mod+shift+f5"
command = "copy"
when = "pane_focused"

[[bind]]
key = "ctrl+alt+c"
command = "copy"
when = "pane_focused"

Keys use lowercase names joined with +, with modifiers in the order meta, ctrl, shift, alt; a key written in another order never fires and is reported. mod means Command on macOS and Ctrl on Linux and Windows; literal ctrl, meta, and alt do not change by platform. Named keys include up, down, left, right, space, escape, enter, backspace, tab, delete, insert, home, end, pageup, pagedown, f1 to f24, and the keypad operators numpad_add, numpad_subtract, numpad_multiply, and numpad_divide. An alt combination matches the key’s position, so on macOS alt+z is Option + Z whatever character it types.

The optional when value sets the context:

`when`	Applies to
none	Global in the main window
`pane_focused`	Main window, file pane focused
`terminal_focused`	Main window, terminal focused
`viewer`	Viewer commands (named `Viewer:` in the Keybindings tab)
`editor`	Editor commands (named `Editor:` in the Keybindings tab)

A context binding wins over a global one on the same key. A focused terminal keeps every key for the shell except terminal commands and terminal_focused bindings, and main-window bindings do not fire while a dialog is open.

To disable a default binding:

[[bind]]
key = "f8"
command = "-"

See Keyboard shortcuts for the defaults.