The nash Command#

Nash installs a command line tool named nash. It is a separate program from nash-gui, the one that draws the window. That split is deliberate: nash can start the GUI, control a running one, and even replace the application on disk without replacing itself.

Run nash with no arguments and it starts the GUI, exactly like nash start. Every other form runs a subcommand. Some open a window, some talk to a window that is already running, and many print a result and exit.

Check that it works#

Open a shell inside Nash and run:

nash --version
nash --help

Since Nash 0.11.5, nash version prints the same version information as nash --version or nash -V, without starting the GUI.

Help text wraps to the width of your terminal (Nash 0.8.1 or newer). Every subcommand has its own help, for example nash update --help.

Subcommands you will use most#

Command	What it does
`nash start [-- PROG]`	Starts the GUI. Runs `PROG` instead of your shell, picks a directory with `--cwd`, or asks a running Nash for a new tab with `--new-tab`.
`nash ssh [user@]host[:port]`	Opens an SSH session in a Nash window.
`nash serial`	Opens a serial port. The baud rate is set with `--baud` and defaults to 9600.
`nash connect DOMAIN`	Connects to a multiplexer domain from your configuration.
`nash cli`	Controls a running Nash: list panes, split, spawn, send text, rename tabs, fold panes. See below.
`nash mux`	Manages the multiplexer server and its sessions. See Multiplexer sessions.
`nash update`	Checks for a newer release and installs it. See Updating Nash.
`nash config sync`	Merges the settings your build adds into your TOML files. See Configuration Sync.
`nash agent-status`	Registers the coding agent hooks that drive tab and pane status. See Connect Your Coding Agent.
`nash telemetry [on\|off\|status]`	Controls the usage-telemetry preference. See below.
`nash imgcat`	Shows an image in the terminal.
`nash ls-fonts`, `nash show-keys`	Explain which fonts Nash uses, and list the active key assignments.
`nash set-working-directory`	Tells the terminal your current directory with an OSC 7 escape sequence.
`nash record`, `nash replay`	Record a terminal session as an asciicast, and play one back.
`nash shell-completion --shell SHELL`	Prints a shell completion script. See below.

This table is not the full list. Run nash --help to see every command that your build supports.

Usage telemetry#

Since Nash 0.9.0, official release builds enable opt-out usage telemetry through PostHog US Cloud. Ordinary source builds (including cargo build --release), debug/test builds, CLI-only commands, headless mux servers, and --skip-config launches do not report usage. Reporting requires an optimized build explicitly marked as production by the release process.

The GUI reports a start event when it first opens a window and at most one active-day reporting attempt per installation per UTC day after focus or user interaction. Each event contains only a random installation ID, event name, timestamp, Nash version, OS family, and CPU architecture. No terminal input/output, commands, keystroke contents, clipboard contents, paths, titles, usernames, or hardware identifiers are included. There is no session recording or person-profile creation. The ID is not derived from your account or hardware. PostHog still sees the source IP of the HTTPS request; Nash asks it to skip geolocation and does not include the real IP as an event property.

nash telemetry status
nash telemetry off
nash telemetry on

off and on save the preference in your configuration directory's nash.toml. You can also disable it directly:

[telemetry]
enabled = false

Configuration sync preserves an explicit false; deleting or commenting out the setting does not opt out. For custom Lua configurations, set config.enable_telemetry = false instead.

Set DO_NOT_TRACK=1 or NASH_DISABLE_TELEMETRY=1 in the GUI's launch environment to disable reporting regardless of configuration. Any non-empty value other than 0 or false opts out; whitespace is ignored and false is case-insensitive. nash telemetry on cannot override an environment opt-out or make a development build report. A macOS Dock launch need not inherit your shell environment, so use the TOML preference for that case.

status (also the default for nash telemetry) inspects the current CLI's preference, build, and environment, not a running GUI or successful delivery. It sends no events and does not create telemetry state. Make sure the CLI and GUI use the same configuration directory, especially with NASH_CONFIG_DIR or XDG_CONFIG_HOME overrides.

Preference changes take effect on configuration reload and are checked before each request; an in-flight request cannot be recalled. Opt out before the first GUI launch to prevent its initial event. Telemetry opt-out does not disable the separate update check.

Options that apply to every command#

Three options come before the subcommand:

Option	What it does
`--skip-config`, `-n`	Starts without loading `nash.lua`.
`--config-file PATH`	Uses this configuration file instead of the normal lookup. It cannot be combined with `-n`.
`--config name=value`	Overrides one configuration value. Repeat the option for more than one value.

nash --config-file ~/test/nash.lua start

nash config sync ignores all three. It works on the TOML files in your configuration directory, not on a Lua file.

Control a running Nash with `nash cli`#

nash cli connects to the Nash that is running and asks it to do something. These subcommands are available:

list and list-clients show windows, tabs, panes, and connected clients.
split-pane, spawn, and move-pane-to-new-tab change the layout.
activate-pane, activate-pane-direction, get-pane-direction, and activate-tab move focus or report where it would go.
send-text and get-text write to a pane and read its text.
set-tab-title, set-window-title, and rename-workspace change names.
adjust-pane-size, zoom-pane, and fold-pane change pane sizes.
kill-pane closes a pane.

nash cli list
nash cli list --format json
nash cli set-tab-title "build"
nash cli fold-pane --toggle

Commands that act on one pane accept --pane-id to select it explicitly. Without it, Nash uses NASH_PANE if set; otherwise it uses the focused pane of the most recently interacted-with client. The fold-pane command is covered in Scripting pane folding.

Three options control how nash cli finds its target:

Option	What it does
`--prefer-mux`	Skips GUI discovery and uses the first configured Unix mux domain, unless `NASH_UNIX_SOCKET` overrides it.
`--no-auto-start`	Does not start a server automatically.
`--class NAME`	Finds a GUI that you started with `--class NAME`.

A nonempty NASH_UNIX_SOCKET takes precedence, even over --prefer-mux. Local GUI panes normally inherit their GUI's socket. Without that override, Nash tries GUI discovery (unless --prefer-mux is set), then the first configured Unix mux domain; it reports an error if none is configured.

IDs are instance-local. When switching from a GUI to the mux server, clear both NASH_UNIX_SOCKET and NASH_PANE, then get IDs from that server's list output. An inherited pane ID can identify an unrelated pane in another instance. Use the same environment and flags for subsequent commands.

nash mux is different: it always targets a unix domain from your configuration, and it owns the server lifecycle, such as installing the server binary and managing sessions.

Tab state commands (Nash 0.11.9 or newer)#

Command	Effect
`move-tab --index N`	Moves the tab to a zero-based, non-negative index within its server window. The index must be in range.
`set-tab-color COLOR`	Sets a custom color using the same parser as Lua `tab:set_color`. Use `--reset` instead of `COLOR` to clear it.
`set-tab-zen true` or `set-tab-zen false`	Sets the tab-scoped Zen flag, never global Zen Mode.

All three accept either --tab-id ID or --pane-id ID, not both. With neither, Nash resolves the current pane as above and uses its tab. An unknown tab or pane is an error. Quote colors containing # or spaces.

For example, this helper targets the first configured Unix mux domain without starting a server. Replace 7 and 12 with IDs from its list output:

mux_cli() {
  env -u NASH_UNIX_SOCKET -u NASH_PANE nash cli --prefer-mux --no-auto-start "$@"
}
mux_cli list --format json
mux_cli move-tab --tab-id 7 --index 0
mux_cli set-tab-color --pane-id 12 '#123456'
mux_cli set-tab-color --tab-id 7 --reset
mux_cli set-tab-zen --tab-id 7 true
mux_cli set-tab-zen --tab-id 7 false

These commands also work on a connected GUI. For server-owned tabs, color, tab-scoped Zen state and order are shared with other attached clients and survive detach/reattach while the server runs. In a GUI mixing local and mux tabs, only the mux tabs participate in server order; other domains keep their slots.

Since Nash 0.11.9, list --format json includes these tab-level fields on each pane row:

color: the normalized custom color string, or null when unset.
zen_mode: the tab-scoped Zen flag, independent of GUI-global Zen Mode.
is_active_tab: whether the server has selected this tab in its window.

These values repeat across all panes of a split tab. is_active still means the active pane within its tab, even in an unselected tab. Rows follow the connected instance's tab order, including move-tab changes; the compact table output is unchanged. Run each command with --help for its full synopsis.

Shell completions#

Nash prints completion scripts for your shell:

# Bash: add this line to ~/.bashrc
source <(nash shell-completion --shell bash)

# Zsh: write the script into a directory on your fpath
mkdir -p ~/.zfunc
nash shell-completion --shell zsh > ~/.zfunc/_nash
# then add "fpath=(~/.zfunc $fpath)" to ~/.zshrc, before "compinit"

# Fish
nash shell-completion --shell fish > ~/.config/fish/completions/nash.fish

Since Nash 0.8.1 the completions cover the config, update, mux, and agent-status commands. Generate the script again after you update Nash, so that it matches the commands your build has.

Where `nash` lives#

How nash reaches your PATH depends on how you installed Nash:

macOS app bundle. The bundle keeps nash next to nash-gui, in Nash.app/Contents/MacOS, and macOS does not put that folder on your PATH. Since Nash 0.5.3 Nash appends the folder to the PATH of every process it starts, so nash works in a pane without a shell profile edit. The folder goes last, so a copy that you installed yourself still wins. This applies to processes that Nash starts, not to other terminal applications.
AppImage. Nash puts the folder that holds the AppImage's tools first on the PATH of the processes it starts.
Windows installer. The installer adds Nash's install folder to the system PATH.

Nash also sets two environment variables for the processes it starts:

Variable	Value
`NASH_EXECUTABLE_DIR`	The folder that holds the running Nash executable.
`NASH_EXECUTABLE`	The full path of the running Nash executable.

Use them in scripts that must run the nash that belongs to the terminal you are in, regardless of your PATH:

"$NASH_EXECUTABLE_DIR/nash" --version

The coding agent hooks use this form. See Connect Your Coding Agent.

Next steps#

Updating Nash explains nash update.
Configuration Sync explains nash config sync.
The FAQ answers common questions.