User commands

User commands turn shell commands into named Newt actions. They can use the focused file, the selection, and both pane paths, then run in a terminal or as a background operation.

Manage them from the Commands tab in Settings. Press F9 to search and run the commands available for the current item or selection.

Define a command

Commands are stored as [[command]] entries in settings.toml:

[[command]]
title = "Archive Selection"
run = "tar czf {{ file.stem }}.tar.gz {{ files | map(attribute='name') | map('shell_quote') | join(' ') }}"
key = "alt+z"
terminal = true
keep_terminal_open = true
applies_to = "selection"

key, terminal, keep_terminal_open, silent, and applies_to are optional. applies_to can be file, directory, or selection; omit it to allow any focused item. This controls when the command is offered, not which input focus receives its keyboard shortcut.

With terminal = true, Newt opens a terminal tab in the active pane’s directory and runs the command there. Set keep_terminal_open = true to keep that tab open after the command exits, even if behavior.keep_terminal_open is disabled. A command cannot override the global setting in the other direction.

With terminal = false (the default), Newt runs the command as an operation and normally reports it in the Operations panel. Set silent = true for a non-terminal command that should show no progress window or panel row. A failed silent command becomes visible so the error is not lost. silent is ignored in terminal mode, and keep_terminal_open is ignored in operation mode.

Template values

The run value is a Minijinja template. These values describe the current context:

Value	Meaning
file	Focused file object.
file.name	Filename including its extension.
file.path	Full path.
file.source	Original path for a virtual entry such as a search result, when applicable.
file.stem / file.ext	Filename without its extension / extension without the dot.
file.is_dir	Whether the focused item is a directory.
file.size / file.modified	Size in bytes / Unix modification timestamp, when available.
files	Selected files, or a one-item list containing file when nothing is selected.
dir / other_dir	Current path of the active / other pane.
hostname	Current session’s hostname.
env.NAME	An environment variable, for example env.HOME.

Use shell_quote for any value placed into a shell command:

{{ file.path | shell_quote }}

Other Newt filters include basename, dirname, stem, ext, regex_replace, and join_path. Standard Jinja filters such as map, join, upper, and lower are also available.

Ask for input

prompt() and confirm() collect input before the command runs:

[[command]]
title = "Create checksum"
run = "{{ confirm('Create a SHA-256 file?') }}sha256sum {{ file.name | shell_quote }} > {{ prompt('Output file', file.name ~ '.sha256') | shell_quote }}"
terminal = true
applies_to = "file"

Newt first scans the template, displays a dialog containing all requested confirmations and fields, then renders it again with the answers. Cancelling or declining a confirmation prevents the command from running.

The Commands tab includes a compact template reference while editing a command.