peanutbutter(1)

📦 version 0.5.1, in alpine 3.24

💅 peanutbutter(1) — like, the actual manual page, bestie

okay so this is the manual page for peanutbutter, and we're gonna get you fluent in it. it's a Wayland screen locker for touch-based Linux mobile devices — yes, phone-shaped Linux. iykyk. 🎀

✨ NAME ✨

peanutbutter — a Wayland screen locker for touch-based Linux mobile devices 🫶

🌸 SYNOPSIS 🌸

peanutbutter [options]

that's it. that's the whole vibe. options only, no positional nonsense. 💅

🦋 DESCRIPTION 🦋

it's a lock screen for Linux mobile, bestie. specifically designed for Sxmo (wayland edition). so if you're on Sxmo wayland, this is literally your girl. ✨

💜 OPTIONS 💜

  • -d, --debug — debug mode, which does two things: it lets you quit on any keypress, and it prints verbose logging. it's insecure, so like… be aware. 🙈
  • -T, --notouch — disables touch support.
  • -F, --nofeedback — disables touch feedback.
  • -f, --font font — sets the font family.
  • -t, --tries tries — how many incorrect touches you get before the locker goes into a deeper lock. 0 means unlimited, and the default is 10.
  • -L, --deeplock seconds — timeout in seconds for deeplock mode, during which the device cannot be unlocked. default is 20.
  • -p, --paranoid — paranoid mode! the deeplock timeout gets doubled every single time it's reached, so successive attempts get harder and harder. no cap.
  • -1 — 1x1 touch grid. insecure. see CONTROLS.
  • -2 — 2x2 touch grid (1=topleft, 4=bottomright). see CONTROLS.
  • -3 — 3x3 touch grid (1=topleft, 9=bottomright). see CONTROLS.
  • -4 — 4x4 touch grid (0=topleft, f=bottomright). see CONTROLS.
  • -s, --statuscommand command — runs this command for a status line. it should run continuously, and each new output line becomes the status line. ⚠️ this parameter should be the last parameter provided! any further parameters get passed to the command. 👑

🎀 CONTROLS 🎀

by default, the screen is segregated into 4 quadrants — that's resolution 2, for the record:

  1. Top left
  2. Top right
  3. Bottom left
  4. Bottom right

the passcode is literally any combination of these, and you configure it through the environment variable PEANUTBUTTER_PASSCODE, which takes a sequence of digits representing the quadrants. like 1132 = top left, top left, bottom left, top right. and fun fact: that's also the default passcode if the environment variable isn't set. 🍓

there is no confirm or clear option, bestie. the passcode is checked after each touch and stored in a stack with the exact length of the passcode. so if you mess up, just start tapping the sequence anew. that's the whole strategy. 💀

a touch gets acknowledged by flipping the background — and note that this only provides an indication of whether the touch was registered, not whether it's a valid touch in the passcode sequence. plus the feedback covers the entire screen and will not specifically highlight the quadrant you tapped. that's on purpose, as a security measure. 🧚

🔥 SECURITY 🔥

for extra security, visual feedback can be disabled entirely by passing the -F or --nofeedback option. slay.

another way to level up your security is to set the parameter -3 and change the resolution to 3 (3x3 = 9 quadrants), which gives you this configuration:

1 2 3

4 5 6

7 8 9

you can even go up to -4, which gives you this next configuration (4x4 = 16 quadrants):

0 1 2 3

4 5 6 7

8 9 a b

c d e f

by default, if a certain number of touches (10 by default) did not lead to a successful unlock, the locker goes into a deeper lock state and shows a red background. this is a time-out state during which the device cannot be unlocked — it times out after a number of seconds (20 by default) and goes back to normal lock mode. it's a security measure to prevent brute-force attacks. periodt.

the number of tries is configured via --tries, and the timeout (in seconds) via --deeplock. you can set --paranoid to make the timeout double each time the deep lock state is reached — which may lead to the timeout being so long that you need to force a hard reboot. 😭 like, genuinely. be careful with that one.

this program implements the ext-session-lock-v1 protocol. so if peanutbutter inadvertently crashes, your information is not exposed. 🫶 iconic behaviour, honestly.

🌈 ENVIRONMENT 🌈

  • PEANUTBUTTER_PASSCODE — the passcode to use, each character refers to a quadrant. see CONTROLS. ⭐

👑 AUTHORS 👑

  • Anjandev Momi <anjan@momi.ca>
  • Maarten van Gompel <proycon@anaproy.nl>

Peanutbutter is licensed under the GNU Affero General Public License v3.

💀 SEE ALSO 💀

sxmo(7)

and that's the page!! 🦋 this version is dated 2025-07-01, straight out of the General Commands Manual — so go forth, lock your phone, tap your quadrants, and don't forget --paranoid is a commitment. 🎀✨💅

📦 where this page comes from