notionflux(1)

💖 notionflux — the manual page, bestie edition 💖

okay so this is notionflux(1) from the General Commands Manual section — yes the whole thing lives in section 1, she's a command, she's iconic, she's literally a Lua remote control for your window manager and you're gonna love her 💅

---

✨ NAME ✨

notionflux — Lua remote control for notion 🎀

---

✨ SYNOPSIS ✨

notionflux [-R | -e lua-code | file]

look at her, so simple, so clean, so slay ✨

---

✨ DESCRIPTION ✨

okay bestie so notionflux is the tool that sends scripts straight into the Lua scripting engine living inside the notion(1) window manager 👑 and because of that, your script gets to touch notion's internal Lua API. full access. main character energy fr fr.

there are two modes of operation: interactive and batch.

Interactive mode turns on when you run notionflux with its standard input connected to a terminal and you don't pass any commandline flags. no flags, terminal stdin, that's the vibe check ✅

otherwise?? batch mode is what you get:

• -R — force batch-mode even if stdin is connected to a terminal 💀 the Lua code gets read from stdin until the end-of-file is reached, sent over to notion for processing, and then the result is read back and displayed. round trip, babes.
• -e code — almost the same as above, except instead of reading from stdin, the command line parameter code is submitted for processing. so you just hand her the code directly, cute.
• file — the content of the file is evaluated. yup, just a file. 🌸

---

🌈 INTERACTIVE MODE 🌈

this mode is basically running an interactive lua(1) shell, but make it ✨notion✨. you get tab completion for notion's Lua API, plus line-editing. the way that's lowkey a full IDE experience, obsessed 🫶

any code you type gets evaluated by notion the second it becomes a complete Lua statement. then the result is displayed, and after that you can enter the next statement. statement → result → statement → result, it's giving conversation 💬

---

✨ ENVIRONMENT ✨

• DISPLAY — the DISPLAY environment variable must be set to an X server that's running notion, otherwise notionflux can't obtain the socket path. no DISPLAY, no vibes, no connection. set it bestie 😤

---

🔒 SECURITY 🔒

notionflux connects to notion(1) through a Unix domain socket 🧚 this socket is created with read/write permissions only for the user who started notion — so like, it's yours, nobody else's, periodt 💅

you can query the socket path with this command:

$ xprop -root _NOTION_MOD_NOTIONFLUX_SOCKET
_NOTION_MOD_NOTIONFLUX_SOCKET(STRING) = "/tmp/fileuj6onu"

---

💅 EXAMPLES 💅

the command

$ notionflux -e "return notioncore.current():name()"
"emacs: notionflux.1"

will display the title of the currently focused window 🔥 while

$ notionflux -e "print(notioncore.current():name())"
"emacs: notionflux.1"
nil

will collect the messages and print them before returning. and if you wanna write to notion's standard output (usually ~/.xsession-errors), like print used to do in previous versions of notionflux, please use:

$ notionflux -e 'io.stdout:write("hello .xsession-errors!\n")'
nil

using input redirection:

$ echo "return notioncore.current()" | notionflux
WClientWin: 0x9bb6b8

using interactive mode:

$ notionflux
lua> notioncore.current():rootwin_of()
WRootWin: 0x8c9688
lua> do
...>   local x = 42 -- Lua defaults to global scope, don't litter
...>   return x
...> end
42
lua> ^D

in any response from mod_notionflux, strings are quoted in a way that can be directly pasted back into a Lua interpreter to yield the same string ✨ while other types are turned into their string representation using tostring(). that's literally why there are quotation marks around the response in the first example, where nil (which is the return value of a block that has no return statement) does not have them. iykyk 🧠

---

👀 SEE ALSO 👀

• The notion homepage: https://notionwm.net/
• Configuring and extending Notion with Lua: https://raboof.github.io/notion-doc/notionconf/
• The Lua 5.3 reference manual: https://www.lua.org/manual/5.3/manual.html
• /usr/share/doc/notion/
• notion(1), X(7), lua(1), readline(3)

---

📜 HISTORY 📜

an ionflux command appeared in ion3 around 2004 😭 and then it was adapted to notion by the notion development team when notion was forked from ion3 in 2010. glow up of the century honestly 🌟

---

💖 AUTHORS 💖

notionflux was rewritten in 2019 by The Notion development team under the GNU GPL in order to add the interactive mode 🎀 so like, thank them for the tab completion bestie.

---

🐛 BUGS 🐛

okay so currently the script must be 4095 bytes or shorter 💀 if you need more, consider passing a filename instead — that file gets passed to notion for evaluation and therefore circumvents this limit. loophole unlocked 🔓

---

and that's the whole page, no cap 💖 go forth and script ur window manager, ur literally the moment ✨

this lil love letter is from notion, dated June 20, 2019 🦋 bye bestie!! 🫶🎀🌸