Command Line Interface

The foresight binary is a small CLI built around two complementary ideas: intercept (turn kernel input events into a stream on stdout) and redirect (turn a stream on stdin back into kernel input events). Between the two you can chain any program that transforms struct input_events — including apps written with the Foresight library.

Usage

Usage: foresight [options] [action]
  arguments:
    -h | --help          Print help.

  actions:
    intercept [files...] Intercept the files and print everything to stdout.
       -g | --grab       Grab the input.
                         Stops everyone else from using the input.
                         Only use this if you know what you're doing!

    redirect [files...]  Redirect stdin to the specified files.

    matches [pattern...] Match key combos in an evtest-format stream read from
                         stdin, printing 'Matched <pattern>' when one is
                         detected.
       --echo-events     Also echo the triggering event line.

    new [name] [template]
                         Create a new app from a template (interchangeable).
                         Run 'foresight new --list-templates' to see the
                         available templates.

    help                 Print help.

Example usages

A Foresight pipeline app can remap keys directly, e.g. an x2y remapper:

#include <linux/input-event-codes.h>
import fs8;
import fs8.mods;

int main() {
    using namespace fs8;

    static constinit auto pipeline =
      context
      | io_manager
      | input_manager
      | intercept[keyboard | required | grab]
      | replace[KEY_X, KEY_Y]
      | output;

    pipeline();
}

Legacy: the intercept–transform–redirect pipeline

The same result can also be achieved by piping foresight intercept through a standalone filter program and back into foresight redirect. This works with a filter written in any language — it just has to pass struct input_event records through unmodified pipes:

keyboard=/dev/input/event1
foresight intercept -g $keyboard | x2y | foresight redirect $keyboard

Creating a new app from a template

foresight new scaffolds a new app (project) from an interchangeable template:

foresight new my-app
foresight new --list-templates   # see the available templates

Matching key combos in evtest output

foresight matches reads an evtest-format event stream from stdin and reports when a key combo (or plain text) occurs in it. This is handy for checking a recorded evtest log for a shortcut, or for verifying what how-to-type emits:

evtest /dev/input/event3 | foresight matches "<ctrl+shift+left>"
cat evtest-results.txt    | foresight matches "<ctrl+Shift+Left>"
foresight how-to-type --evtest "[ctrl+shift+left]" | foresight matches "[ctrl+shift+left]"

Patterns use the same syntax as the typed mod: <...> for a key press, [...] for a key release, <<...>>/[[...]] for ordered variants, or plain text like "test". Each occurrence prints Matched <pattern> at <time> (--echo-events additionally echoes the triggering event line). The exit code is 0 when anything matched and 1 otherwise.