POWERLINEALL(1)

NAME
powerlineall - comprehensive reference for the powerliners 5-binary suite (powerline / powerline-daemon / powerline-config / powerline-render / powerline-lint)

OVERVIEW
powerliners is a 1:1 Rust port of the upstream Python powerline-status project. It ships five cooperating binaries that together replace the entire Python implementation while preserving the existing ~/.config/powerline/ JSON config tree byte-for-byte.

This manpage documents the suite as a whole: invocation order, wire protocol between client and daemon, config-lookup cascade, theme grammar, segment dispatch, and the rendering pipeline. For individual binaries see the per-binary powerline(1), powerline-daemon(1), powerline-render(1), powerline-config(1), powerline-lint(1) pages.

SYNOPSIS
powerline [--socket PATH] EXT [ARGS...]

powerline-daemon [--foreground | --quiet | --replace | --kill] [--socket PATH]

powerline-render EXT [ARGS...]

powerline-config SUBCOMMAND [ARGS...]

powerline-lint [-p PATH]

DESCRIPTION

1. ARCHITECTURE
powerliners splits the rendering pipeline into a long-lived daemon and a thin fork-on-demand client:

•   powerline-daemon — a single Unix-socket server per UID. Loads the JSON config tree once, instantiates segment classes once, holds the theme dictionaries and color palettes in memory.

•   powerline — the lightweight client. Forwards argv + cwd + the environment to the daemon over a Unix socket and copies the rendered statusline to stdout. Falls back to powerline-render when the daemon is unreachable.

•   powerline-render — the direct-render fallback. Same render path as the daemon but no socket; pays the full config-load cost on every invocation.

•   powerline-config — config-introspection helper. Used by shell init scripts to locate the right powerline.sh bindings to source.

•   powerline-lint — static-analysis tool. Validates config.json + theme JSON for unknown segment names, missing color references, malformed before/after formatting strings, and other authoring errors.

2. WIRE PROTOCOL
The powerline client and the powerline-daemon server communicate over an abstract or filesystem Unix socket. The wire format mirrors the upstream C client (vendor/powerline/client/powerline.c lines 126-148):

    hex(argc-1) "\0" argv[0] "\0" argv[1] "\0" ... cwd "\0" env[0] "\0" ... "\0\0"

The server demarshals the request, dispatches to the appropriate Powerline.<ext> extension, and writes the rendered byte stream back. Cross-version clients and servers interop as long as the wire format is preserved.

3. SOCKET PATHS

/tmp/powerline-ipc-<uid>
    Filesystem socket (macOS, FreeBSD, OpenBSD, NetBSD).

\0powerline-ipc-<uid>
    Abstract socket (Linux). Has no filesystem entry; appears only in ss(8) -x and lsof(8) -U under the leading NUL marker. Survives /tmp cleanup races.

Both can be overridden with --socket PATH.

4. CONFIG CASCADE
powerline-render and powerline-daemon search for config.json + theme JSON in this order (first hit wins per key):

1.  $XDG_CONFIG_HOME/powerline/ (falls back to ~/.config/powerline/).

2.  $POWERLINE_CONFIG_PATHS — colon-separated user override roots.

3.  /etc/powerline/ — system-wide overrides.

4.  The bundled defaults shipped with the powerliners package itself (vendor/powerline/powerline/config_files/).

Per-key merging follows the upstream Python mergedicts semantics: deep dictionary merge, REMOVE sentinel for explicit deletion, nested-list append.

5. THEME GRAMMAR
A theme JSON file declares segments: left / right list of segment specs, each segment naming a Python-style segment_data function (mapped in the Rust port to a dispatch table of fn(args: &Map<String, Value>, info: &Map<String, Value>) -> Option<Value> adapters). The segment returns a list of highlight_groups + contents tuples. The theme's segment_data section can override args , contents, before/after, or the priority for any segment by key.

Color palettes live in colors.json; named colors are referenced from colorschemes/<ext>.json which maps highlight-group names to fg / bg / attrs triples. The theme grammar is the same as upstream and any existing ~/.config/powerline/ tree works unchanged.

6. SEGMENT DISPATCH
Segments fall into three categories:

common
    Cross-extension segments (battery, network, weather, mail, hostname, cwd, vcs branch). Located under src/ported/segments/common/.

shell
    Shell-specific segments ( last_status, last_pipe_status, jobnum, continuation_marker).

tmux
    Tmux-specific segments ( session_name, window_index, pane_count).

The player segment family additionally supports per-player adapters (spotify, itunes, mocp, mpd, cmus, rhythmbox, clementine) through a common PlayerSegment base, faithfully mirroring upstream's class hierarchy.

7. DAEMON LIFECYCLE
powerline-daemon defaults to forking into the background after binding the socket (powerline-daemon & in ~/.profile), re-execs on SIGHUP (to pick up config changes without dropping the socket), and exits cleanly on SIGTERM.

•   --foreground keeps the daemon attached to the terminal (useful for systemd Type=simple units).

•   --replace kills any existing daemon on the same socket and takes over.

•   --kill sends SIGTERM to the running daemon and exits.

•   --quiet suppresses startup banner / log output (analogous to upstream).

8. INVOCATION FROM SHELLS

  zsh
    function powerline_precmd() {
        PS1="$(powerline shell left \
            --last-exit-code=$? \
            --jobnum=$(jobs -p | wc -l))"
    }
    precmd_functions+=(powerline_precmd)

  bash
    PROMPT_COMMAND='PS1="$(powerline shell left \
        --last-exit-code=$? \
        --jobnum=$(jobs -p | wc -l))"'

  tmux
    set -g status-interval 2
    set -g status-left  "#(powerline tmux left)"
    set -g status-right "#(powerline tmux right)"
    set -g status-style "bg=colour234,fg=colour231"

  vim
    " let g:powerline_pycmd = 'py3'
    set rtp+=~/.local/lib/python3.X/site-packages/powerline/bindings/vim/
    set laststatus=2
Vim integration retains the Python plumbing because vim's :python host is the only IPC path for inline script execution; the rendered content still comes from the powerline binary, just via a thin Python helper.

9. CONFIG INTROSPECTION
powerline-config subcommands:

tmux setup
    Print the tmux source-file fragment to wire powerline statusline + status-left / right + window status formats. Used by powerline.sh during shell init.

tmux source
    Print the path to the active powerline.tmux fragment so downstream source-file directives can pick it up.

shell command
    Print the shell command that should be set as $POWERLINE_COMMAND — useful for shells whose init script needs to detect the binary.

shell uses [SEGMENT]
    Exit 0 iff SEGMENT is referenced from any active theme. Used to gate optional segment setup (e.g. skip powerline.sh sourcing of git completion when no git segment is active).

10. LINTING
powerline-lint walks the config + theme cascade and reports:

•   Unknown segment function names referenced from themes.

•   Missing color names referenced from colorschemes/.

•   Malformed before/after/contents format strings (unbalanced braces, unknown variable references).

•   Type errors in JSON keys (e.g. a string where an integer priority is required).

•   Tuple-length bounds violations (e.g. a 1-element tuple where 2-elements are required).

11. ENVIRONMENT

POWERLINE_COMMAND
    The command invoked by shell + tmux integrations. Set to powerline to use this native binary.

POWERLINE_CONFIG_PATHS
    Colon-separated config search roots.

POWERLINE_CONFIG_OVERRIDES
    key=value overrides applied to the resolved config dict per extension.

POWERLINE_NO_DAEMON
    If set, the powerline client skips the daemon socket and execs powerline-render directly. Useful when debugging daemon startup races.

XDG_CONFIG_HOME
    User config root; falls back to ~/.config if unset.

12. FILES

~/.config/powerline/config.json
    User config root.

~/.config/powerline/themes/<ext>/
    Per-extension theme JSON files.

~/.config/powerline/colorschemes/<ext>.json
    Highlight-group color mappings.

~/.config/powerline/colors.json
    Named color palette.

/tmp/powerline-ipc-<uid>
    Daemon Unix socket (macOS / BSD).

\0powerline-ipc-<uid>
    Daemon Unix socket (Linux abstract).

/etc/powerline/
    System-wide config overrides.

13. EXIT STATUS

0   Successful render ( powerline , powerline-render).

0   Daemon started successfully ( powerline-daemon).

0   Lint clean ( powerline-lint).

1   Daemon unreachable AND fallback failed ( powerline).

2   Config or theme lint errors ( powerline-lint).

64  Bad invocation / unrecognized argument.

14. PERFORMANCE NOTES
The Python upstream pays a ~50–150 ms interpreter import tax on every render. Because tmux re-renders the statusline at status-interval and shell prompts re-render on every keystroke (with precmd hooks fired), the import tax compounds into a noticeable interactive latency.

powerliners is a single static binary: zero-import, zero-GC, no GIL. With a warm powerline-daemon the per-render cost is dominated by the socket roundtrip (typically <500 μs). Without the daemon, powerline-render pays a one-time config-load cost (~10 ms) and emits in <2 ms thereafter.

15. SEE ALSO
powerline(1), powerline-daemon(1), powerline-render(1), powerline-config(1), powerline-lint(1), tmux(1), zsh(1), bash(1), vim(1)

Upstream Python powerline-status : https://powerline.readthedocs.io.

Source / issues: https://github.com/MenkeTechnologies/powerliners.

AUTHORS
MenkeTechnologies. 1:1 Rust port of the upstream Python powerline-status project (Kim Silkebækken et al.).

BUGS
Report at https://github.com/MenkeTechnologies/powerliners/issues.