CLI reference

Reference every nbsp command and option, including prompt metadata, data formats, refresh controls, Git markers, and exit statuses.

Synopsis

nbsp init zsh [--detached]
nbsp prompt [--status N] [--duration-ms N] [--jobs N]
nbsp data [--status N] [--duration-ms N] [--jobs N] [--format lines|nul]
nbsp refresh [--cwd PATH] [--notify] [--force]
nbsp cache clear
nbsp --help
nbsp --version

init zsh

Print Zsh integration code to standard output.

eval "$(nbsp init zsh)"

The default installs the fixed prompt, hooks, asynchronous refresh lifecycle, redraw handling, and external editor binding.

eval "$(nbsp init zsh --detached)"

--detached installs the same data and redraw lifecycle without modifying PROMPT or RPROMPT. It publishes NBSP_DATA, nbsp_data_update_functions, and nbsp_prompt_escape.

prompt

Render the built-in prompt from the current directory, cache, environment, and supplied command metadata.

nbsp prompt --status 1 --duration-ms 2400 --jobs 2

The command never starts Git or Node.

data

Serialize the same cache-only facts for a custom consumer:

nbsp data --status 1 --duration-ms 2400 --jobs 2

--format lines is the default and emits percent-encoded key=value records. --format nul emits alternating raw key and value records separated by NUL bytes.

Neither format starts Git. See Direct data output for the schema and safe parsing examples.

refresh

Collect and publish detailed Git status for one directory:

nbsp refresh --cwd "$PWD"

The Zsh integration normally runs this command asynchronously. --force does not bypass locking, timeout, validation, or atomic cache publication.

cache clear

Remove cache and lock files owned by nbsp:

nbsp cache clear

Git markers

Process exit status

Optional prompt context failures do not prevent a prompt from being rendered. For example, absence of a repository or active NVM version is normal.