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

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 use the pane you run them in, which Nash identifies through the NASH_PANE environment variable. Pass --pane-id to target another pane. 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`	Connects to a background multiplexer server instead of a running GUI.
`--no-auto-start`	Does not start a server automatically.
`--class NAME`	Finds a GUI that you started with `--class NAME`.

nash cli acts on the Nash you are running in. 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.

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.