Configuration on nux

Global config

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

The global config file controls defaults, discovery, pickers, and session groups for all projects.

Location#

nux follows the XDG Base Directory Specification. The config file is located at:

$XDG_CONFIG_HOME/nux/config.yaml

On most systems this resolves to ~/.config/nux/config.yaml. If $XDG_CONFIG_HOME is set to a custom path, nux uses that instead.

You can override the config directory at runtime with --config-dir <path>. This also changes where nux looks for project configs (<path>/projects/).

If the config file does not exist, nux applies built-in defaults silently (no error).

Project config

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

Each project is defined in a YAML file under the nux config directory:

$XDG_CONFIG_HOME/nux/projects/<name>.yaml

On most systems this is ~/.config/nux/projects/<name>.yaml. The file name (without .yaml) becomes the project name on the CLI.

Session name normalization#

The tmux session name is derived from the project name with these transformations:

Dots (.), colons (:), and spaces are replaced with underscores (_)
Leading dashes are stripped
Consecutive underscores are collapsed to one
Trailing underscores are stripped

For example, a file named my.cool-project.yaml produces the session name my_cool-project.

Session groups

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

Groups are named lists of project names in global config under the groups key. They let you start or stop several projects at once without typing each name.

Defining groups#

groups:
 work:
 - api
 - web
 - workers
 personal:
 - blog
 - dotfiles

Each entry is a project name - the basename of a file in ~/.config/nux/projects/ (without .yaml), or any name resolvable via project_dirs or zoxide.

Usage#

Start every session in a group:

Default session

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

When a project has no config file under ~/.config/nux/projects/, nux builds a session from default_session in global config. This is why commands like nux blog can work with zero project file - the template provides the layout.

No default_session set#

If default_session is omitted from global config entirely, nux still creates a session - it just gets a single empty window with no commands. This is a bare tmux session rooted at the project directory.

Environment variables

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

The env field in a project config sets session-scoped environment variables using tmux set-environment. Every pane in that session inherits them.

Syntax#

Values are strings. You can reference existing process environment variables with ${VAR} and use default fallbacks with ${VAR:-default}:

env:
 NODE_ENV: development
 PORT: "3000"
 DATABASE_URL: "${DATABASE_URL_DEV}"
 LOG_LEVEL: "${LOG_LEVEL:-info}"

Interpolation#

Environment variable values go through the same interpolation pipeline as other config fields:

Custom variables - {{var}} placeholders are resolved from the vars block
Environment expansion - ${VAR} references are expanded using Go’s os.ExpandEnv

This means you can combine both:

Custom variables

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

The vars field in project config defines named values you can reuse across the file.

`{{var}}` interpolation#

Use double-brace names in any string field - root, hooks, env values, and window or pane fields (including pane command when using the object pane form):

vars:
 app_name: myapp
 deploy_env: staging

root: ~/projects/{{app_name}}

env:
 APP_NAME: "{{app_name}}"
 DEPLOY_ENV: "{{deploy_env}}"

windows:
 - name: api
 panes:
 - ./bin/{{app_name}}-api

Resolution order#

Interpolation happens in this order:

Editor IntelliSense

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

JSON Schemas ship in the nux repository for both config types:

schemas/global.schema.json - global config.yaml
schemas/project.schema.json - per-project YAML under projects/

Point your YAML language server at these schemas to get completion, validation, and hover docs in your editor.

The schemas include:

Required panes — windows without at least one pane are flagged inline.
Layout validation — named layouts (tiled, main-vertical, etc.) get autocomplete, and custom tmux layout strings are also accepted.
String-or-object shorthands — panes: [nvim] is recognized as valid.

nux config and nux new automatically include the appropriate schema modeline in generated files. For existing configs or manual setup, use one of the methods below.

Configuration on nux

Global config

Location#

Project config

Session name normalization#

Session groups

Defining groups#

Usage#

Default session

No default_session set#

Environment variables

Syntax#

Interpolation#

Custom variables

{{var}} interpolation#

Resolution order#

Editor IntelliSense

`{{var}}` interpolation#