Commands on nux

stop

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux stop <session> [session ...]

Description#

Stops one or more tmux sessions by name. You can pass multiple session arguments in a single invocation.

Session names accept glob patterns (for example web+ matches related session names) and group expansion with the @ prefix (for example @work expands to every session in that group).

stop-all#

nux stop-all

Kills every running tmux session. This is a blunt reset when you want no sessions left running. It is separate from nux stop (which requires at least one session argument).

restart

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux restart <target> [target ...]

Description#

Stops each matching session, then starts it again so changes in the project config are picked up. By default, nux attaches to the last restarted session.

Targets support glob patterns (+ matches any suffix, same as nux and nux stop), @group expansion from the global config, and multiple space-separated names.

Use the :window suffix to restart one or more windows (comma-separated) inside a session without tearing down the rest.

show

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux show <target> [target ...]

Description#

Prints the fully resolved config for one or more projects as YAML. The output reflects the state after interpolation ({{var}} substitution), environment expansion (${VAR}), and root resolution - exactly what nux would use to build the session.

Targets support glob patterns (+), @group expansion, and multiple space-separated names. Multiple projects are written as a YAML stream: one document per project, separated by a --- line.

list

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux list

Alias: nux ls

Description#

Lists all projects that have a config file under ~/.config/nux/projects/, along with their current status.

Column	Meaning
NAME	Project name (derived from the config filename)
STATUS	`running` if a tmux session is active, `-` otherwise
WINDOWS	Number of windows in the running session (blank if not running)
UPTIME	How long the session has been running (blank if not running)
CONFIG	`project` (all listed entries come from config files)
ROOT	The `root` value from the project config, if set

Only projects with explicit config files appear here. Convention-based projects (discovered via project_dirs or zoxide) are not included unless they also have a config file.

config

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux config

Description#

Opens the global nux config in $EDITOR. If the config file does not exist yet, a scaffold with commented examples is created first.

The generated scaffold contains all available settings with sensible defaults. Optional settings are commented out with examples so you can enable them as needed.

Behavior#

When no config exists:

The config directory and projects/ subdirectory are created.
A scaffold config.yaml is written with default values, commented examples, and a schema modeline for editor IntelliSense.
nux prints Created <path>.
If $EDITOR is set, the file is opened in your editor. Otherwise nux prints hint: set $EDITOR to open new configs automatically.

When a config already exists:

ps

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux ps

Description#

Shows currently running tmux sessions in a table.

Column	Meaning
NAME	Session name
WINDOWS	Number of windows in the session
ATTACHED	`yes` if a client is attached, `no` otherwise
UPTIME	How long the session has been running (e.g. `5m`, `1h 32m`)

If no sessions are running, nux prints No running sessions.

This command shows all tmux sessions, not just those started by nux.

Example output#

NAME WINDOWS ATTACHED UPTIME
blog 2 yes 5m
api 3 no 1h 32m
docs 1 no 45m

Notes#

For the full project catalog (including projects without a running session), use nux list.
Uptime is rounded to the nearest minute.

new

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux new <name>

Description#

Creates a new project config file at ~/.config/nux/projects/<name>.yaml and opens it in $EDITOR if set.

The generated config includes a schema modeline for editor IntelliSense and a minimal template:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Drew-Daniels/nux/main/schemas/project.schema.json
windows:
 - name: editor

Edit this file to define your windows, panes, commands, and other project settings.

Behavior#

If a config for <name> already exists, nux exits with an error (it will not overwrite).
The config file is written to disk.
nux prints Created <path>.
If $EDITOR is set, nux opens the new file in your editor.
If $EDITOR is not set, nux prints hint: set $EDITOR to open new configs automatically.

Errors#

config already exists: <path> - a file with that name already exists. Use nux edit <name> to modify it, or nux delete <name> to remove it first.

Examples#

# Create and edit a new project config
nux new blog

# Create without opening an editor (when $EDITOR is unset)
unset EDITOR && nux new api

Post-save validation#

When the editor closes, nux re-loads and validates the config. Errors are printed as [error] and a clean config prints Config valid. If the YAML is unparseable, a syntax error warning is shown instead.

edit

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux edit <name>

Description#

Opens the project config file for <name> in your $EDITOR. The file is located at ~/.config/nux/projects/<name>.yaml.

This is a convenience shortcut - equivalent to running $EDITOR ~/.config/nux/projects/<name>.yaml yourself.

Errors#

$EDITOR is not set - set the EDITOR environment variable in your shell profile (e.g. export EDITOR=nvim).
config not found: <path> - no config file exists for that project name. Use nux new <name> to create one first.

Examples#

# Edit an existing project config
nux edit blog

# Common EDITOR values
export EDITOR=nvim # Neovim
export EDITOR=vim # Vim
export EDITOR=code # VS Code
export EDITOR=nano # Nano

Post-save validation#

delete

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux delete <name> [name ...]

Alias: nux del

Description#

Deletes one or more project config files. By default, nux prompts for confirmation before each deletion.

This only removes config files at ~/.config/nux/projects/<name>.yaml. It does not delete project directories, source code, or stop any running sessions.

Supports glob patterns with + and group expansion with @.

Flags#

Flag	Meaning
`--force`	Skip confirmation prompts

Behavior#

Arguments are expanded (patterns and groups resolved to individual names).
For each target, nux checks that the config file exists.
Unless --force is set, nux prompts: Delete config for "<name>"? [y/N]
If confirmed, the file is deleted and nux prints Deleted config for "<name>".
If declined, nux prints Cancelled. and moves on to the next target.

Errors#

config not found: <path> - no config file exists for that project name.

Examples#

# Delete with confirmation prompt
nux delete old-project

# Delete without prompting
nux delete old-project --force

# Delete multiple projects
nux delete blog api docs

# Delete all projects matching a pattern
nux del web+ --force

# Delete all projects in a group
nux del @deprecated --force

Notes#

If a session for the deleted project is still running, it continues until stopped. Use nux stop <name> first if you want to tear down the session.
After deletion, the project can still start via convention (directory under any configured project_dirs path) or zoxide, but without any custom config.

reset

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux reset

Description#

Removes the global nux config file so you can start fresh. Use --projects to also remove all project config files.

Before anything is deleted, a summary of what will be removed and what will be kept is printed.

Flags#

Flag	Meaning
`--force`	Skip the confirmation prompt
`--projects`	Also remove all project configs

Behavior#

nux checks that config.yaml exists in the config directory.
A preview of what will be removed and what will be kept is printed.
Unless --force is set, nux prompts for confirmation.
The global config file is deleted.
If --projects is set, the projects/ directory and all its contents are also deleted.

Running tmux sessions are not affected by this command.

validate

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux validate [name ...]

Description#

Validates project configuration files and reports errors. Each config is printed with [ok] or [error].

With no arguments: validates all project configs under ~/.config/nux/projects/.
With one or more targets: validates each expanded project. Targets support glob patterns (+), @group expansion, and multiple space-separated names (same rules as nux / nux stop).

What gets checked#

Every project must have at least one window with at least one pane.
Every window must have a name.
Every window must have at least one pane.
layout values must be a recognized tmux layout name or a valid custom layout string.

Example output#

 [ok] blog
 [ok] api
 [error] workers: at least one window is required

If any config has errors, nux exits with a non-zero status.

doctor

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux doctor

Description#

Runs a diagnostic suite for your nux and tmux environment. Each check is reported with [ok], [warn], [fail], or [missing].

Checks performed, in order:

nux version - prints the running version, OS, and architecture
tmux binary - verifies tmux is on PATH and prints its version
Global config - confirms the global config loaded successfully
Zoxide binary - checked only when zoxide: true in global config
Picker binary - checked only when a picker is configured (fzf, gum)
Config directory - verifies ~/.config/nux/projects/ exists
Projects directory - verifies each configured project_dirs path exists
Project configs - validates every project YAML file

If any check fails, doctor exits with a non-zero status and prints “some checks failed.”

completions

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux completions <bash|zsh|fish>

Description#

Prints a shell completion script to standard output for the given shell. Redirect the output to the location your shell loads for completions.

Install examples#

bash

nux completions bash > /etc/bash_completion.d/nux

zsh

nux completions zsh > "${fpath[1]}/_nux"

fish

nux completions fish > ~/.config/fish/completions/nux.fish

Notes#

If you install nux via Homebrew or Nix, completions are often installed automatically; you may not need the steps above.
You may need elevated permissions for system-wide paths (for example /etc/bash_completion.d).

version

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

nux version

Description#

Prints build metadata: version, git commit, and build date.

Example output#

nux 0.5.0
 commit: a1b2c3d
 built: 2026-04-01T12:00:00Z

When running a development build (via go install or go build without ldflags), the output shows placeholder values:

nux dev
 commit: none
 built: unknown

Changelog#

See the GitHub releases page for release notes and changelogs.

Notes#

Useful when reporting bugs or verifying that your PATH points to the expected install.
Release builds embed version info via -ldflags at compile time.