Required keys

Optional keys

Builtin descriptors

A package can provide shell builtins by declaring them in the manifest:

[{"module": "shell.builtins.k8s", "commands": ["ktl"]}]

The module field names the module within the package that returns a builtin family table (same format as built-in families like shell.builtins.fs). The module is loaded via require() during shell startup.

Mode descriptors

A package can provide shell modes:

[{
    "name": "agent",
    "path": "agent.mode.agent",
    "history": true,
    "prompt": "agent.mode.agent.prompt",
    "completion": {
        "path": "agent.completion.slash",
        "sources": ["agent.completion.source.slash"]
    }
}]

Mode descriptors do NOT include shortcut assignments. Users map F-keys to package modes via ~/.config/lilush/modes.json:

{
    "F4": "agent",
    "F5": "k8s-dashboard"
}

Each key is an F-key, each value is a LILPACK name whose first mode descriptor is activated on that key.

CLI script descriptors

A package can provide standalone CLI commands that are installed as executable scripts in ~/.local/bin/:

["mytool", "myutil"]

Each entry is a command name. The corresponding Lua source must exist in the cli/ subdirectory of the source tree (e.g. cli/mytool.lua). On install, each script is written to ~/.local/bin/<command> with a #!/usr/bin/env lilush shebang prepended (if not already present) and made executable.

CLI scripts are independent files -- they do not participate in module loading. Scripts that need LILPACK modules must initialise the searcher chain themselves:

local lilpack = require("lilpack")
lilpack.init()
local mylib = require("mypackage.utils")

Theme descriptors

A package can extend the theme system by providing section builders (styles for a specific mode) and/or complete theme definitions (palette + overrides).

The theme manifest field is an object with two optional sub-fields:

Section builders — provide styles for a named theme section:

{
    "theme": {
        "sections": [
            {"name": "agent", "builder": "agent.theme"}
        ]
    }
}

The builder field names a module that returns a function. The function receives the active palette table and returns an RSS table for the section. It is called each time the theme changes to rebuild section styles from the new palette.

Theme definitions — provide a complete selectable theme:

{
    "theme": {
        "definition": {
            "name": "solarized",
            "module": "solarized.theme"
        }
    }
}

The module field names a module that returns a table in the same format as bundled catalog entries: { palette = {...}, shell = {...}, markdown = {...} }.

A single package can declare both sections and definition if needed.

See THEMES for the full theme architecture and API.

Official Lilush Packages repo

By default lilpack install will try to install remote packages from the official Lilush Packages HTTP Repo. This can be overriden with the LILPACK_REPO_URL environment variable.

Packages in the official HTTP repo come from lilpacks repo.

Environment variables

Signing (lilpack pack)

lilpack pack requires LILPACK_SIGN_KEY to be set:

1. Reads the OpenSSH ed25519 private key (must be unencrypted)

2. Computes a canonical SHA-256 digest over all package content

3. Signs the digest with Ed25519

4. Stores the 64-byte signature and 32-byte pubkey in __lilpack

The embedded pubkey must exactly match the trusted verification key. Packages with a mismatched embedded key are rejected.

Verification (lilpack install)

lilpack install always verifies signatures before installing:

• Verification passes -- installed

• Verification fails -- rejected

• No trusted key available -- rejected

Verification at load time (lilpack.init)

Every package is verified when the package system initialises. The built-in public key is used by default; LILPACK_PUB_KEY overrides it. Verification requires both:

• the embedded pubkey matches the trusted key

• the signature verifies against that key

• Verification passes -- loaded

• Verification fails -- skipped with error

• No trusted key available -- no packages loaded

Canonical digest algorithm

The digest is a SHA-256 hash over a deterministic serialization of all package content (excluding signature and pubkey):

1. Manifest fields in fixed order: version, name, pkg_version, description, modules, author, license, dependencies, builtins, modes, cli, theme. Each present field contributes key=tostring(value)\0.

2. Module sources in sorted name order. Each module contributes module:name=source\0.

3. CLI script sources in sorted name order. Each script contributes cli:name=source\0.

4. All parts are concatenated and hashed with SHA-256.

Key fingerprints

Public key fingerprints are the first 16 hex characters of SHA-256 over the raw 32-byte public key. Displayed by lilpack info and lilpack verify.

Examples

# Pack and sign a source directory:
setenv LILPACK_SIGN_KEY ${HOME}/.ssh/lilpack_sign.ed
lilpack pack /path/to/lilpack/source

# Install a package (verified against the built-in key):
lilpack install llm-0.1.0.lilpack

# Install with a custom trusted key:
setenv LILPACK_PUB_KEY ${HOME}/.ssh/lilpack_sign.pub
lilpack install llm-0.1.0.lilpack

# Verify a package without installing:
lilpack verify llm-0.1.0.lilpack -k ~/.ssh/lilpack_sign.pub