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.

notion                                            June 20, 2019                                    notionflux(1)