POWERLINE(1)

📦
version 2.8.4 · 6 versions
, in debian trixie, ubuntu resolute

💖 POWERLINE(1) — the powerline prompt & statusline script, bestie edition 💖

okay so. you opened the manual for powerline, which lives in section 1 of the Powerline manual, and honestly? iconic of you. this is the script that makes your prompt and your statusline look like a whole vibe, and I'm gonna walk you through every single flag because you deserve to know all of them. no gatekeeping here. 🎀

✨ NAME ✨

powerline — the Powerline prompt and statusline script. that's the whole thing. that's the girl. 💅

🌸 SYNOPSIS 🌸

powerline EXT [SIDE] [-rMODULE] [-wWIDTH] [--last-exit-code=INT]
          [--last-pipe-status=LIST] [--jobnum=INT]
          [-cKEY.KEY=VALUE]… [-tTHEME.KEY.KEY=VALUE]… [-RKEY=VAL]…
          [-pPATH]… [--socket=ADDRESS]

🦋 DESCRIPTION 🦋

so the way this works is you hand powerline a couple of positional things and then a pile of flags, and it renders your little statusline situation. here's the tea on each piece. ✨

  • EXT — the Extension, aka the application you're launching this powerline command for. usually it's your shell or tmux. it also supports wm. extensions, specifically wm.awesome. 👑
  • SIDE — the Side, and there are four moods you can pick from:
    • left and right — left side and right side respectively, obviously. 💁
    • above — emits lines that are supposed to be printed just above the prompt.
    • aboveleft — it's like concatenating above with left, except the glow-up is that only one Python instance gets used in this case. efficiency queen.
    • also, this whole argument may be omitted for wm.* extensions. no biggie.

💅 OPTIONS 💅

  • -r, --renderer-module MODULE — the renderer module, bestie. usually it's something like .bash or .zsh (note the leading dot) which maps to powerline.renderers.{ext}{MODULE}. it can also be a full module name (which must contain at least one dot, or end with a dot if it's a top-level module), or a powerline.renderers submodule (in case there are no dots at all). so many options and all of them valid. we love range.
  • -w, --width WIDTH — the maximum prompt width. heads up: this triggers truncation of some segments. yes, it will cut your segments off. that's the whole point. 😭
  • --last-exit-code INT — the last exit code. that's it, that's the flag. if your last command flopped, this is where it gets recorded. 💀
  • --last-pipe-status LIST — like --last-exit-code, but this one is supposed to contain a space-separated array of statuses, representing the exit statuses of commands in one pipe. so if you piped a whole chain of stuff, this holds all of their little verdicts.
  • --jobnum INT — number of jobs. your background job count, right there.
  • -c, --config-override KEY.KEY=VALUE — configuration overrides for config.json. here's how it works: it gets translated to a dictionary and merged with the dictionary obtained from the actual JSON configuration. specifically, KEY.KEY=VALUE becomes {"KEY": {"KEY": VALUE}} and then that gets merged recursively. VALUE may be any JSON value — anything that isn't null, true, false, or doesn't start with a digit, {, or [ is treated like a string. and if VALUE is omitted entirely? then the corresponding key is removed. bye girl. 👋
  • -t, --theme-override THEME.KEY.KEY=VALUE — like the above, but theme-specific. quick note: THEME should point to an existing and used theme for this to have any effect — but honestly, it's fine to use any theme here. do what you want. 🫶
  • -R, --renderer-arg KEY=VAL — like the above, but it provides an argument for the renderer. it's supposed to be used only by shell bindings, to provide various data like last-exit-code or last-pipe-status. and iykyk, those bindings aren't using --renderer-arg for historical reasons: --renderer-arg was added later. lore. 📜
  • -p, --config-path PATH — path to the configuration directory. if this is present, then configuration files will only be sought in the provided path. may be provided multiple times to search in a list of directories. stack them up. 🍓
  • --socket ADDRESS — socket address to use in daemon clients. it's always a UNIX domain socket on linux and a file socket on Mac OS X. not used here tho — it's present only for compatibility with other powerline clients. ⚠️ and listen closely: this argument must always be the first one, and it must be in the form --socket ADDRESS — no = and no short form allowed (that's in other powerline clients, not here). so don't get cute with it. 🙈
  • -h, --help — display help and exit. the classic. the icon. 🎀

👑 AUTHOR 👑

Written by Kim Silkebækken, Nikolay Pavlov, Kovid Goyal and contributors. The glyphs in the font patcher are created by Fabrizio Schiavi. literal legends, all of them. 💜

🚨 REPORTING BUGS 🚨

Report powerline bugs to https://github.com/powerline/powerline/issues. go tell them what's wrong, they wanna know, fr fr. 🐛

🌈 SEE ALSO 🌈

okay that's the whole page bestie, you made it to the end, I'm so proud of you. 🥹 this was the beta version of the page, dated January 22, 2025, so if you're reading it way later, hi from the past, hope your statusline is slaying. periodt. 💅✨

📦 where this page comes from