CLI reference

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

Synopsis

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

-h is an alias for --help; -V is an alias for --version.

init zsh

Print Zsh integration code to standard output.

eval "$(nbsp init zsh)"

The default installs hooks, asynchronous refresh, redraw handling, a private external-editor widget, and the opinionated Zsh prompt (a normal NBSP_DATA callback). It binds Alt+E only in the emacs, viins, and vicmd keymaps where that key is undefined.

Emitted code sets _NBSP_BIN to the resolved absolute path of the nbsp process that ran init, so later hooks do not depend on PATH order. Re-run init after moving or upgrading the install location.

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

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

--autosuggest is independent of prompt mode. It adds ordinary history ghost text and bounded, point-in-time cd suggestions described in Autosuggestions. Options may appear in either order.

data

Serialize the non-spawning foreground snapshot for Zsh or other consumers:

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

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

The command never starts Git or Node. It still performs repository discovery, HEAD reads, cache validation, and current-directory collection. Cache counters are used only when the cached branch matches the current HEAD. If getcwd() fails, the command exits with status 1 and writes no data. See Data protocol for the schema and complete-frame parsing rules.

refresh

Collect and publish detailed Git status for one directory:

nbsp refresh --cwd "$PWD"

The Zsh integration normally runs this command asynchronously. After native same-filesystem repository discovery, the worker runs the equivalent argument vector below with Git-selector environment variables removed:

git --no-optional-locks -C ROOT --git-dir=GIT_DIR --work-tree=ROOT status \
  --porcelain=v2 --branch --show-stash --untracked-files=normal \
  --ignore-submodules=dirty --no-renames

The counters are porcelain-v2 record counts: each ordinary tracked record can increment the staged count, modified count, or both; each unmerged record increments the conflict count; and each ? record increments the untracked count. With --untracked-files=normal, one untracked-directory record can represent more than one filesystem path. Dirty submodule worktrees are ignored and rename detection is disabled. Ahead, behind, and stash values come from the porcelain headers.

Before replacing the cache pathname, nbsp reads HEAD again and requires it to match the collected branch or detached object label. --force does not bypass locking, timeout, output and parser limits, this branch-coherence check, cache validation, or pathname replacement. --notify writes its newline for every completed worker outcome, including a benign no-op or an error; it is a completion signal, not a success byte.

Repository-discovery failure is a benign no-op for refresh: this includes no repository and also a nonexistent or unreadable --cwd, because the command does not distinguish those outcomes. They return status 0 without publishing a snapshot.

cache clear

Remove recognized cache snapshot and temporary-snapshot names present in the cache directory scan:

nbsp cache clear

Persistent per-repository lock files remain in place so concurrent refreshes continue to synchronize on the same inode. Clearing does not acquire those locks. If a temporary pathname selected by the scan is also in use by an in-flight refresh, that refresh can fail to publish.

dirs

Emit a bounded snapshot of immediate child directories under --cwd for the Zsh autosuggestion worker. For a nested typed path, the worker passes its resolved typed parent rather than scanning the shell’s entire working tree:

nbsp dirs --cwd "$PWD" --format nul

The protocol consists of alternating NUL-delimited keys and values. A consumer must ignore the entire frame unless it is well-formed, starts with schema_version=1, ends with complete=1, and the producer succeeds. The command follows directory symlinks, sorts names bytewise, and rejects a scan that exceeds 1,024 entries or 64 KiB. A 50 ms timer terminates an overlong scan with SIGALRM, so a consumer must also reject a partial frame. This is an internal, versioned boundary; scripts needing a general file-listing interface should use standard filesystem tools.

Process exit status

dirs can instead terminate from SIGALRM; the numeric status reported by a parent shell for that signal is shell- and platform-dependent. Optional prompt context failures do not prevent a prompt from being rendered. For example, absence of a repository or recognized NVM_BIN version is normal, while failure to obtain the current directory is not.