CLI Flags

Usage Syntax

nash [OPTIONS] [SCRIPT]

Nash accepts standard shell flags (bash/sh compatible), Nash-specific flags for sandboxing, and general options.

Positional Arguments

SCRIPT

string

Shell script file to execute from the host filesystem.

nash script.sh
nash ./deploy.sh
nash /path/to/file.sh

If no script is provided and stdin is a TTY, Nash starts in interactive REPL mode.

Standard Shell Flags

These flags are compatible with bash, sh, and other POSIX shells.

-c

string

Execute a command string and exit.

nash -c "echo hello | grep hello"
nash -c 'pwd && ls'

Equivalent to bash’s -c flag.

-i

boolean

Force interactive mode even when stdin is not a TTY.

nash -i
echo "pwd" | nash -i

Useful for debugging or when you want the REPL despite piped input.

nash -l
nash --login

Can be combined with script execution:

nash -l script.sh

-s, --stdin

boolean

Read commands from stdin instead of starting the REPL or running a script.

cat commands.txt | nash -s
nash -s < input.sh

When stdin is not a TTY, -s is implicit if no script or -c is provided.

-e, --errexit

boolean

Exit immediately if any command exits with a non-zero status.

nash -e script.sh
nash -e -c "false && echo 'not reached'"

Equivalent to set -e in bash. Critical for robust scripts.

-u, --nounset

boolean

Treat references to unset variables as errors.

nash -u script.sh
nash -u -c 'echo $UNDEFINED_VAR'  # Errors out

Equivalent to set -u in bash.

-x, --xtrace

boolean

Print each command to stderr before executing.

nash -x script.sh

Output example:

+ echo "hello"
hello
+ mkdir /tmp/test

Equivalent to set -x in bash. Essential for debugging scripts.

-v, --verbose

boolean

Print each input line to stderr as it is read, before parsing.

nash -v script.sh

Equivalent to set -v in bash.

Combining Shell Flags

Flags can be combined for powerful script control:

nash -eux script.sh  # errexit + nounset + xtrace

Nash-Specific Flags

These flags control Nash’s sandboxing and VFS behavior.

-U, --user

string

default:"user"

Set the session username. Creates /home/<username> and sets $USER, $LOGNAME, and $HOME.

nash -U alice
nash --user bob

Prompt output:

alice@nash:/home/alice$

The username must be 1-32 characters, alphanumeric plus _ and -.

-C, --cwd

string

Override the starting directory inside the VFS.

nash -C /tmp
nash --cwd /var/log

Default: /home/<username>The directory is created if it doesn’t exist.

-E, --env

string

Set environment variables inside Nash using KEY=VALUE format. Repeatable.

nash -E DEBUG=true -E API_URL=http://localhost:8080
nash --env FOO=bar --env BAZ=qux

Variables set with -E override defaults and are accessible via $KEY:

nash -E CUSTOM=value -c 'echo $CUSTOM'
# Output: value

-B, --bind

string

Mount a host directory into the VFS read-write. Format: HOST:VFS. Repeatable.

nash -B ./project:/project
nash --bind ./data:/data --bind ./config:/etc/config

Files in the host directory become accessible at the VFS path:

nash -B ./src:/src -c 'ls /src'

Writes inside the VFS path are reflected on the host filesystem.

--bind-ro

string

Mount a host directory into the VFS read-only. Format: HOST:VFS. Repeatable.

nash --bind-ro ./data:/data
nash --bind-ro /etc/config:/config

Attempts to write to the mount point will fail:

nash --bind-ro ./data:/data -c 'echo test > /data/file.txt'
# Error: read-only mount

Mount Examples

Single mount
Multiple mounts
Script with mount

nash -B ./project:/project -C /project

Starts Nash inside /project with host ./project mounted read-write.

nash -B ./src:/src -B ./data:/data --bind-ro ./config:/config

Mounts three directories: src and data read-write, config read-only.

nash --bind ./logs:/var/log analyze.sh

Runs analyze.sh with host ./logs accessible at /var/log in the VFS.

General Options

--rcfile

string

Source a custom rc file instead of the default ~/.nashrc.

nash --rcfile ./custom.nashrc
nash --rcfile /path/to/init.sh

The rc file is sourced from the VFS if present, otherwise from the host filesystem.

--norc

boolean

Do not source any rc file on startup.

nash --norc
nash --norc script.sh

Useful for clean, reproducible environments.

--version

boolean

Print the Nash version and exit.

nash --version

Output:

nash 0.1.0

-h, --help

boolean

Print help information and exit.

nash --help
nash -h

Displays usage, flags, and examples.

Flag Combinations

Nash flags can be combined to create powerful, customized environments.

Development Environment

nash -U dev \
     -C /workspace \
     -B ./project:/workspace \
     -E DEBUG=true \
     -E NODE_ENV=development

Sets up:

User: dev
Working directory: /workspace
Host ./project mounted at /workspace
Environment: DEBUG=true, NODE_ENV=development

Strict Script Execution

nash -eux \
     --bind-ro ./config:/config \
     -E ENV=production \
     deploy.sh

-e: Exit on error
-u: Error on undefined variables
-x: Trace execution
Read-only config mount
Production environment variable

Isolated Testing

nash --norc \
     -C /tmp \
     -E TEST_MODE=true \
     test-script.sh

No rc file loaded
Starts in /tmp
Custom test environment

Default Environment Variables

Nash sets these environment variables by default (overridable with -E):

Variable	Default Value
`USER`	Username from `-U` (default: `user`)
`LOGNAME`	Same as `USER`
`HOME`	`/home/<user>`
`SHELL`	`nash`
`TERM`	`xterm-256color`
`LANG`	`en_US.UTF-8`
`LC_ALL`	`en_US.UTF-8`
`PATH`	`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`
`PWD`	Current working directory
`OLDPWD`	Previous directory (for `cd -`)
`HOSTNAME`	`nash`
`SHLVL`	`1`
`_`	`nash`
`-`	Active shell flags (e.g., `eux`)

Overriding Defaults

nash -E HOME=/custom/home -E PATH=/custom/bin -c 'echo $HOME:$PATH'
# Output: /custom/home:/custom/bin

Execution Mode Priority

When multiple flags are provided, Nash follows this priority order:

-c CMD → Execute command string and exit
-s → Read from stdin
SCRIPT → Run script file
-i → Force interactive REPL
Stdin is TTY → Interactive REPL (default)
Stdin is pipe → Read from stdin (implicit -s)

If -c is provided, all other execution modes are ignored.

Examples

Quick Command

nash -c "echo \$USER is in \$PWD"

Interactive with Custom User

nash -U alice -C /tmp

Script with Debugging

nash -x -e script.sh

Mounted Workspace

nash -B ./project:/work -C /work

Production Script Runner

nash -eux \
     --bind-ro ./config:/config \
     --bind ./data:/data \
     -E ENV=prod \
     --norc \
     run.sh

Get Started

Usage Guide

Core Features

Examples

Architecture

Usage Syntax

Positional Arguments

Standard Shell Flags

Combining Shell Flags

Nash-Specific Flags

Mount Examples

General Options

Flag Combinations

Development Environment

Strict Script Execution

Isolated Testing

Default Environment Variables

Overriding Defaults

Execution Mode Priority

Examples

Quick Command

Interactive with Custom User

Script with Debugging

Mounted Workspace

Production Script Runner

See Also

Build docs developers (and LLMs) love

Get Started

Usage Guide

Core Features

Examples

Architecture

​Usage Syntax

​Positional Arguments

​Standard Shell Flags

​Combining Shell Flags

​Nash-Specific Flags

​Mount Examples

​General Options

​Flag Combinations

​Development Environment

​Strict Script Execution

​Isolated Testing

​Default Environment Variables

​Overriding Defaults

​Execution Mode Priority

​Examples

​Quick Command

​Interactive with Custom User

​Script with Debugging

​Mounted Workspace

​Production Script Runner

​See Also

Build docs developers (and LLMs) love

Usage Syntax

Positional Arguments

Standard Shell Flags

Combining Shell Flags

Nash-Specific Flags

Mount Examples

General Options

Flag Combinations

Development Environment

Strict Script Execution

Isolated Testing

Default Environment Variables

Overriding Defaults

Execution Mode Priority

Examples

Quick Command

Interactive with Custom User

Script with Debugging

Mounted Workspace

Production Script Runner

See Also