Data protocol

Reference the versioned nbsp data protocol, its line and NUL formats, safe parsing rules, and command metadata.

nbsp data serializes the same cache-only facts that power nobsprompt. It never starts Git.

Readable line format

$ nbsp data --status 1 --duration-ms 2400 --jobs 2
schema_version=1
cwd=/Users/example/project
path=/U/e/project
status=1
duration_ms=2400
jobs=2
node_version=22.14.0
git_present=1
git_valid=1
git_branch=main
...

cwd is the full physical working directory and path is its abbreviated display form. Detached callbacks can render NBSP_DATA[cwd] after passing it through nbsp_prompt_escape; they do not need to start realpath.

The default output is a versioned sequence of key=value records. Values use percent encoding, so common values remain readable while spaces, newlines, %, =, control bytes, and other exceptional bytes remain unambiguous.

Consumers should:

• require a schema version they understand;
• select records by key rather than position;
• ignore unknown keys added by a compatible schema;
• percent-decode values before use;
• never evaluate the output as shell code.

Lossless NUL format

--format nul emits alternating raw keys and values separated by NUL bytes:

typeset -A data
while IFS= read -r -d '' key && IFS= read -r -d '' value; do
  data[$key]=$value
done < <(nbsp data --format nul)

Command substitution cannot safely preserve NUL delimiters. Parse the records from a process substitution, pipe, or file descriptor.

Command metadata

Direct consumers can provide the same command context used by the Zsh integration:

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

Detached integration

Detached mode parses this protocol into the atomic NBSP_DATA associative array and adds the Zsh lifecycle around it:

• pre-command and pre-prompt lifecycle tracking;
• command timing and background job collection;
• asynchronous nbsp refresh;
• atomic NBSP_DATA replacement;
• callback execution;
• automatic ZLE redraw.

See Data and lifecycle for the NBSP_DATA schema, callbacks, prompt escaping, and first-refresh behavior.