Directories

The shell creates these directories on first launch if they don't exist:

Init scripts

On startup, the shell mode executes init scripts in this order:

1. /etc/lilush/init.lsh — system-wide (if exists)

2. ~/.config/lilush/init.lsh — user (if exists)

Both files use the LSH scripting format. Execution stops on the first non-zero exit code within each file.

A typical init.lsh:

# Set prompt blocks
setenv LILUSH_PROMPT=user,dir,git

# Set theme
theme gruvbox

# Define aliases
alias ll ls -la

# Python venvs directory
setenv LILUSH_PYTHON_VENVS_DIR=/home/user/.venvs

User modes

Custom modes are loaded from ~/.config/lilush/modes.json. This file maps shortcut keys to LILPACK package names:

{
    "F5": "my-package-name"
}

The mode module, prompt, completion, and sources are discovered from the LILPACK's manifest. Built-in mode names (shell, lua, wiki) cannot be overridden.

If a mode's package is not installed, the shell prints a warning and skips that mode instead of failing to start.

Shortcut conflicts are resolved automatically: if a user mode requests a reserved shortcut (F1–F3) or one already taken, it is reassigned to the next free key in the F4–F12 pool.

1. Entry start_shell.lua

Seeds the RNG, registers SIGINT handler, starts a LEV event loop (lev.run()), then within the event loop calls shell.new() and shell:run().

2. Shell constructor shell.lua:new()

1. Sets SHELL=/usr/bin/lilush

2. Initializes LILPACK (lilpack.init()), which replaces default Lua searchers with LILPACK and script-local searchers and clears package.path

3. Creates a MNEME-backed history store (see MNEME for storage details)

4. Loads built-in modes in order: shell → lua → wiki. For each mode, load_mode() creates:

   • Prompt object (from the mode's prompt module)

   • Completion object (with all configured sources)

   • History object (backed by the shared store)

   • Input object (wiring prompt, completion, and history together)

   • Mode object via the mode module's new(input, config)

5. Binds mode shortcuts: F1 (shell), F2 (lua), F3 (wiki)

6. Reads ~/.config/lilush/modes.json and loads user modes from LILPACKs

3. Shell mode initialization shell/mode/shell.lua:new()

The shell mode constructor runs during step 4 above:

1. check_config_dirs() — creates ~/.config/lilush/ and ~/.local/share/lilush/ if missing

2. load_config() — executes /etc/lilush/init.lsh then ~/.config/lilush/init.lsh

3. Re-applies LILUSH_PROMPT — if init.lsh set the variable via setenv, the prompt blocks are updated to match (the prompt object was created before init.lsh ran)

4. Sets initial prompt state — populates home, user, hostname, pwd

5. Updates completion — registers aliases as a completion source

4. Main event loop shell.lua:run()

1. Verifies TTY, sets raw mode

2. Probes terminal text-sizing support

3. Checks and enables Kitty keyboard protocol

4. Enables bracketed paste mode

5. Clears screen, displays initial prompt

6. Enters the main loop, processing "execute" and "combo" events

Built-in modes

Built-in shortcuts (F1–F3) are reserved and cannot be reassigned.

Mode switching

Press a mode's shortcut key to switch to it. CTRL+d from a non-shell mode returns to the shell mode. Each mode preserves its own input state (content, cursor position, history position) independently.

Mode contract

Every mode must expose these methods:

• run() — execute the current input

• get_input() — return the mode's input object

• can_handle_combo(combo) — return true if the mode handles the given key combo

• handle_combo(combo) — process a key combo, return true to trigger redraw

Available blocks

Blocks are always rendered in this fixed order regardless of the order specified in the configuration. A trailing $ is always appended.

Configuring prompt blocks

Via LILUSH_PROMPT env var — comma-separated list of block names:

setenv LILUSH_PROMPT=user,dir,git

The default if unset is user,dir.

Via the prompt builtin — toggle individual blocks at runtime:

prompt git          # toggle git block on/off
prompt git secrets  # toggle multiple blocks
prompt              # show enabled/disabled blocks

LILUSH_PROMPT resolution order

1. Prompt object is created — reads LILUSH_PROMPT from environment, falls back to "user,dir"

2. init.lsh runs — may setenv LILUSH_PROMPT=...

3. After init.lsh, LILUSH_PROMPT is re-read and prompt blocks are updated

This means all three scenarios work:

• No config, no env var → defaults to user,dir

• LILUSH_PROMPT set in parent shell → read at prompt creation

• LILUSH_PROMPT set in init.lsh → re-applied after config loading

Global (all modes)

Top-level builtins

These are handled directly by the shell mode because they need access to the mode's internal state:

Regular builtins

Dispatched through the builtins registry (shell.builtins):

Filesystem: ls (-a -t -l), cd, mkdir (-p), rm (-r -f), rmrf, ../.../etc. (shorthand for cd ../../...), files_matching (execute over matching files)

File viewing: kat — file viewer with pager and markdown rendering (-m --raw --pager)

Environment: setenv/export, unsetenv, envlist (optional regex filter)

Process management: ps (-a -o -x --detailed --json --text -k -p -u --sort), exec (replace shell process), job (list start kill attach reap)

Networking: dig (see dig --help), netstat (-l --source --destination), wgcli (up down)

History: history (-n --compact --time-only)

Snippets: zx (snippet launcher)

MNEME: mneme — MNEME database management

Packages: lilpack — LILPACK package management (list, modules, install, verify)

Desktop: notify — desktop notification via Kitty protocol (--after --title)

Builtin fork modes

Each builtin declares a fork mode that controls how it executes:

Builtins may also declare:

• extra — receives the shell's jobs context as a third argument (used by kat, job)

• pre_fork — a hook that runs in the parent before forking, can set environment variables or short-circuit execution

Fork modes by builtin:

Alias expansion

Aliases are expanded at:

• Start of input

• After | (pipe)

• After &&, ||, ; operators

Aliases are simple text substitution — the alias name is replaced with the alias value before parsing.

Secret URI format

mneme://secrets/key_name

• key_name — the key in the encrypted secrets keyspace

Example:

setenv DB_PASSWORD=mneme://secrets/db_password

Encryption

Secrets are encrypted at rest using an Ed25519 SSH key. Set the LILUSH_ENCRYPTION_KEY environment variable to the path of your SSH key:

setenv LILUSH_ENCRYPTION_KEY=~/.ssh/id_ed25519

Without this key, secrets set/get/fetch operations will fail with an error. Unencrypted keyspaces (history, session) are unaffected.

The secrets builtin

secrets fetch resolves each mneme://secrets/ URI, reads the secret from the encrypted keyspace, and overwrites the environment variable with the actual value. You can fetch specific variables by name or omit the argument to fetch all secret-backed vars.

When using secrets set, omitting the value argument opens an interactive prompt with hidden input, avoiding the secret appearing in shell history.

Persist modes

After fetching, secrets remain in the environment for a limited number of commands before being automatically cleared (restored to mneme:// URIs).

Secrets in scripts

Fetched secrets are inherited by child processes, including LSH scripts run via shebang. Scripts do not re-run init.lsh, so the inherited environment (with fetched secrets) is preserved as-is.

lilush -c <command> (mini mode)

Creates a minimal shell with no prompt, no completion, and no history. Executes the given command and exits. Does not load init.lsh.

lsh <script> (script mode)

If lilush is invoked as lsh via symlink, it executes an LSH script file. Script arguments are exposed as env vars: ${0} (script path), ${1}..${N} (positional args), ${#} (arg count). Does not load init.lsh. See LSH for the scripting format.

Shell-managed

User-configurable

Secrets