NAME

     notionflux — Lua remote control for notion

SYNOPSIS

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

DESCRIPTION

     notionflux is a tool to send scripts to the Lua scripting engine inside the notion(1) window
     manager.  The script can thus access notion's internal Lua API.

     There are two modes of operation, interactive and batch.  Interactive mode is enabled by
     running notionflux with its standard input connected to a terminal and without passing any
     commandline flags.

     Otherwise, batch mode is enabled:

     -R      Force batch-mode even if stdin is connected to a terminal.  Lua code is read from
             stdin until the end-of-file is reached, is sent to notion for processing, and the
             result is read back and displayed.

     -e code
             Almost the same as above, except instead of reading from stdin, the command line
             parameter code is submitted for processing.

     file    The content of the file is evaluated.

INTERACTIVE MODE

     This mode is similar to running an interactive lua(1) shell.  Tab completion for notion's
     Lua API is available, as well as line-editing.

     Code that has been entered is evaluated by notion as soon as it is a complete Lua statement.
     The result is displayed after which the next statement can be entered.

ENVIRONMENT

     DISPLAY  The DISPLAY environment variable must be set to an X server running notion in order
              for notionflux to obtain the socket path.

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.  The socket path can be queried
     with the following 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.  In order to write to notion's
     standard output (usually ~/.xsession-errors), like print used to 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().  This is why there are quotation marks around
     the response in the first example where nil (which is the return value of a block which has
     no return statement) does not have them.

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.  It was adapted to notion by the notion
     development team when notion was forked from ion3 in 2010.

AUTHORS

     notionflux was rewritten in 2019 by The Notion development team under the GNU GPL in order
     to add the interactive mode.

BUGS

     Currently, the script must be 4095 bytes or shorter.  If you need more, consider passing a
     filename, which is passed to notion for evaluation and therefore circumvents this limit.