$  elsie help

The elsie commands

Everything elsieOS does can be done with the elsie command, at the machine or over SSH. Each command below shows the help text it prints on the machine (elsie help COMMAND).

Made from elsieOS 0.1.59 · refreshed with every release

elsie - the elsieOS command. elsie help COMMAND (or elsie COMMAND --help) explains one.

e is short for elsie and works with every command: e status is elsie status.

What elsie help prints
elsie - the elsieOS command. 'elsie help COMMAND' (or 'elsie COMMAND --help') explains one.
'e' is short for 'elsie' and works with every command: 'e status' is 'elsie status'.

  What is going on
    elsie status        version, updates, backups, network, disks, GPU; 'elsie status --live' is the
                        status screen of the machine's monitor, redrawn every few seconds
    elsie logs [WHAT]   recent messages: problems (the default), models, comfyui, apps, updates, backups,
                        network, system ('-f' follows them, '--since 2h' looks further back)

  Models and apps
    elsie models        the model library: list, info, import, set, load, unload, remove
    elsie apps          AI apps next to the models (ComfyUI, Open WebUI, ...): install, update, allow, remove
    elsie gpu-test      how fast models reach the GPU (pinned-memory copy speed)
    elsie hardware      what this machine has (card, memory, drives) and what that means for elsieOS
    elsie dashboard     the web dashboard (https): its addresses, password, who may connect

  Versions
    elsie update        install the newest version ('elsie update check' only looks)
    elsie updates       where updates come from and what happens by itself: server, auto
    elsie versions      the installed versions
    elsie rollback      go back to the version before, and stay there ('elsie rollback undo')

  Backups
    elsie backup        backups of settings, identity and people's files: add, now, list, recovery, ...
    elsie restore       make a new install the machine in a backup (finds the recovery file by itself)

  Setting the machine up (each explains what it changes)
    elsie menu          menus for installing, setting up and the status (type a number)
    elsie setup         a guided walk through all of these, in order
    elsie name          the machine's name           elsie network      address (automatic or fixed)
    elsie remote        Tailscale                    elsie ssh          keys, tunnels, host keys, port
    elsie server        model server port, who may connect
    elsie alerts        problems to your phone       elsie timezone     time zone
    elsie screensaver   on/off, idle time, clock     elsie console-password
    elsie migrate       what can come over from an old system on another drive
    elsie ups           a UPS on USB: an alert and a clean shutdown on a power cut
    elsie boot-other    start another system on this machine's drives (once, or from now on)
    elsie secureboot    Secure Boot here: on or off, through the shim, is the elsieOS key enrolled
    elsie install       put elsieOS on one of this machine's drives (from a USB stick that runs elsieOS)

What is going on

elsie status

version, updates, backups, network, disks, GPU; elsie status --live is the status screen of the machine's monitor, redrawn every few seconds

elsie status            what is running: version, boot entry, updates, backups, health, network,
                        disks, GPU
elsie status --live     the status screen (as on the machine's monitor): address, GPU memory and
                        temperature, each model and where it is, requests now, ComfyUI, updates,
                        backups, health - redrawn every few seconds; q quits

elsie logs

recent messages: problems (the default), models, comfyui, apps, updates, backups, network, system ('-f' follows them, '--since 2h' looks further back)

Also: elsie log

elsie logs [WHAT] [-f] [--since TIME]
  WHAT     problems   warnings and errors since the last start, and any failed service (the default)
           models     the model server: requests, loads, switches
           comfyui    ComfyUI
           apps       the other apps, their installs and the app firewall
           updates    update checks, installs, trial boots
           backups    the nightly backups
           network    the network and Tailscale
           system     everything since the last start
           or the name of any service
  -f       keep showing new messages as they come (Ctrl+C stops)
  --since  how far back, for example 30min, 2h, 3d (default: the last 100 messages)

Models and apps

elsie models

the model library: list, info, import, set, load, unload, remove

elsie models - the model library of elsieOS (run as 'elsie models ...').

    elsie models list                       the models elsieOS has, with their settings
    elsie models import [--from DIR|URL]    bring models over from an Ollama install (another drive
                                            of this machine, a folder, or another computer over the
                                            network: --from sftp://USER@COMPUTER[/FOLDER]); asks which ones
    elsie models set NAME [options]         change a model's settings (see 'elsie models set --help')
    elsie models remove NAME                delete a model from elsieOS
    elsie models info NAME                  everything elsieOS knows about one model
    elsie models download [NAME ...]        download models whose files are missing (after a restore from a
                                            backup without model copies): the same versions, from where they
                                            came from (Ollama's library, Hugging Face), checked by SHA-256
    elsie models sources [--json]           whether each model could be downloaded again (the same version: the
                                            same manifest, or the same model file when the registry rewrote the
                                            parts it generates itself - Hugging Face does)
    elsie models load NAME                  put a model on the GPU now (it stays for the usual idle time;
                                            'set NAME --pin' keeps it there)
    elsie models unload NAME                take a model off the GPU now (a kept-loaded one stays)
    elsie models catalogue [--json]         the models elsieOS offers, each rated for this machine (fits on the
                                            graphics card / with a shorter context / too big), from the same memory
                                            estimate the model server loads by
    elsie models get ID|NAME [--yes]        download a model by its catalogue id (or any Ollama library name): the
                                            licence first, then the download (resumable, SHA-256 checked), then
                                            the usual import
    elsie models vision NAME [FILE|URL]     give a model image input: its vision part (the one published for its
                                            base model, e.g. for a text-only copy of an Ollama model, or a given
                                            projector file/address, checked by SHA-256 and by its shape) | off;
                                            one given by address is fetched again after a restore

Each model lives in /srv/models/<id>/: the model file, an optional vision file (for image input),
a licence, and profile.toml with its settings. The model server (elsie-modeld) reads them; after a
change it is told to reload. Design: docs/model-server.md.
elsie models list options
usage: elsie models list [-h]

options:
  -h, --help  show this help message and exit
elsie models info options
usage: elsie models info [-h] name

positional arguments:
  name

options:
  -h, --help  show this help message and exit
elsie models import options
usage: elsie models import [-h] [--from SOURCE] [--select SELECT] [--yes] [--context CONTEXT]
                           [--parallel PARALLEL] [--pin] [--link] [--missing]

options:
  -h, --help           show this help message and exit
  --from SOURCE        folder with Ollama's 'manifests' and 'blobs', or another computer:
                       sftp://USER@COMPUTER[:PORT][/FOLDER] (its home folder when no folder is
                       given)
  --select SELECT      model numbers or 'all' (instead of asking)
  --yes                use the suggested settings instead of asking
  --context CONTEXT
  --parallel PARALLEL
  --pin
  --link               link to the files instead of copying (tests)
  --missing            only fill in the files of models whose settings are here already (after
                       'elsie restore'), keeping those settings
elsie models set options
usage: elsie models set [-h] [--context CONTEXT] [--parallel PARALLEL] [--pin] [--unpin]
                        [--nickname NICKNAME] [--clear-nicknames]
                        name

positional arguments:
  name

options:
  -h, --help           show this help message and exit
  --context CONTEXT    tokens per request
  --parallel PARALLEL  requests at the same time
  --pin                keep it loaded
  --unpin              load it only when asked
  --nickname NICKNAME  another name programs may use (repeatable)
  --clear-nicknames
elsie models remove options
usage: elsie models remove [-h] [--yes] name

positional arguments:
  name

options:
  -h, --help  show this help message and exit
  --yes
elsie models download options
usage: elsie models download [-h] [--missing] [--yes] [names ...]

positional arguments:
  names

options:
  -h, --help  show this help message and exit
  --missing   (the default) every model whose files are missing
  --yes
elsie models sources options
usage: elsie models sources [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json
elsie models load options
usage: elsie models load [-h] name

positional arguments:
  name

options:
  -h, --help  show this help message and exit
elsie models unload options
usage: elsie models unload [-h] name

positional arguments:
  name

options:
  -h, --help  show this help message and exit
elsie models vision options
usage: elsie models vision [-h] [--sha256 SHA256] [--yes] name [source]

positional arguments:
  name
  source           a .gguf vision projector (file or https address), or 'off'

options:
  -h, --help       show this help message and exit
  --sha256 SHA256  the file's SHA-256 (needed for an address elsieOS does not know)
  --yes            replace a vision part without asking
elsie models catalogue options
usage: elsie models catalogue [-h] [--json]

options:
  -h, --help  show this help message and exit
  --json
elsie models get options
usage: elsie models get [-h] [--yes] [--context CONTEXT] [--parallel PARALLEL] [--anyway]
                        [--catalogue-only]
                        name

positional arguments:
  name

options:
  -h, --help           show this help message and exit
  --yes                download without asking (this accepts its licence)
  --context CONTEXT
  --parallel PARALLEL
  --anyway             also when it is too big for this machine
  --catalogue-only     refuse names that are not in the catalogue

elsie apps

AI apps next to the models (ComfyUI, Open WebUI, ...): install, update, allow, remove

elsie apps - AI apps that share the GPU with the chat models (run as 'elsie apps ...').

    elsie apps                        the app catalogue and what is installed: version, state, port, size
    elsie apps install NAME           download and install an app from the catalogue (says what and where first)
    elsie apps update NAME            install the catalogue's newer version; the one before is kept for a rollback
    elsie apps rollback NAME          back to the version before the last update
    elsie apps start | stop | restart NAME
    elsie apps logs NAME              its recent messages
    elsie apps allow NAME [WORDS]     who may reach it: local, home, tailscale, anywhere, address ranges
                                      (the firewall; without WORDS it shows the setting)
    elsie apps remove NAME [--all]    remove the program (keeps your data unless --all)
    elsie apps import comfyui         bring models, custom nodes, settings, workflows, inputs and outputs
                                      over from an old system (another drive, read-only), --from DIR, or
                                      another computer: --from sftp://USER@COMPUTER[/FOLDER]
    elsie apps import-custom [NAME]   bring an app of your own over from an old system: without NAME it lists
                                      the services found there ('elsie apps import-custom help' says more)

Each app is described by an app.toml in the catalogue (/usr/share/elsieos/apps; docs/app-format.md) and runs as
elsie-app@NAME.service from its own folder (/srv/apps/NAME: versions/, current, data/, home/).

Apps live on the data partition (/srv/apps/<app>), each with its own Python environment, and update
on their own, not with elsieOS. ComfyUI runs as elsie-comfyui.service on 127.0.0.1:18188; programs
reach it on its usual port 8188 through elsie-modeld, which shares the GPU between it and the chat
models (docs/gpu-sharing.md).

elsie apps import-custom

elsie apps import-custom - bring an app of your own over from an old system (run as 'elsie apps import-custom').

    elsie apps import-custom               the services found on the old system that look like apps of your own
    elsie apps import-custom SERVICE       bring that one over: shows what it found, asks, copies it, starts it
        --from ROOT     the old system's files, already mounted at ROOT (default: this machine's other drives,
                        looked at read-only)
        --as NAME       what the app is called here (default: the old service's name)
        --port N        the port it listens on, when that cannot be read from its command
        --gpu KIND      none | gate[:MIB] | whole[:MIB] - how it shares the graphics card (asked otherwise)
        --busy PATH     (gate) the app's own address that says whether it is using the card ({"busy": true}, or
                        a list of jobs with --busy-statuses queued,running): the card stays lent while it says so
        --release restart   (gate) an app that keeps what it loaded on the card: started again when the room is
                        needed and it has nothing to do
        --job-gpu NAME=MIB|all,...   scheduled jobs (from the old crontab) that need the graphics card
        --plan          show what it would do, change nothing
    elsie apps import-custom --cron              the old crontab's jobs that belong to no service, by folder
    elsie apps import-custom --cron FOLDER       bring those jobs over: a package with no program of its own,
                                                 only its jobs (and the folder, environments they use)
        --yes           take the suggested answers

The old system is only read. The app's folder, the Python environments it runs in (its own, or conda's) and the
model caches it uses are copied into /srv/apps/NAME/home, and the app runs as before: inside its own sandbox that
folder appears where the old home folder was, so paths written into its scripts keep working. A Python
environment that pointed at the old system's Python gets elsieOS's own copy of the same Python version. An app that
reaches other machines over ssh (its scripts call ssh or scp, or push to git remotes over ssh) gets its own SSH folder
with only what those hosts need: their part of ~/.ssh/config, their keys, their known-hosts lines. The result
is a package of your own (/srv/apps/NAME/package.toml): private to this machine, in its backups, started, stopped
and removed like any other app ('elsie apps').

elsie gpu-test

how fast models reach the GPU (pinned-memory copy speed)

elsie gpu-test          how fast a model's weights reach the GPU from pinned memory (the speed that
                        makes switching models fast); needs an NVIDIA GPU

elsie hardware

what this machine has (card, memory, drives) and what that means for elsieOS

elsie hardware - what this machine has for running AI, checked against what elsieOS needs (phase 7.4).

    elsie hardware          the graphics card, memory, processor and drives, each with what it means here
    elsie hardware --json   the same as JSON (the installer, the menus, the web dashboard and the model catalogue read it)
    elsie hardware --brief  two or three lines (shown by 'elsie install')

The numbers it is checked against are version 1's requirements (docs/hardware-support.md, decided 2026-11-16): it
warns, it never refuses. Nothing is changed; it only reads (nvidia-smi, /proc, /sys, lsblk).

elsie dashboard

the web dashboard (https): its addresses, password, who may connect

elsie dashboard - the machine's status and everyday controls in a browser (docs/dashboard.md).

    elsie dashboard                   on or off, its addresses, the certificate's fingerprint, who may connect
    elsie dashboard password          set the dashboard's password (asked twice; everyone is logged out)
    elsie dashboard allow WORDS...    who may connect: local home tailscale anywhere, or address ranges
                                      (default: local home tailscale)
    elsie dashboard new-certificate   make a new certificate (after a name change, for example)
    elsie dashboard on | off          switch it on or off

The dashboard answers at https://ADDRESS/ (port 443) with a certificate made on this machine: the browser warns
once that it does not know it - check the fingerprint it shows against the one here and on the status screen.
It runs as its own user and can change nothing itself: every change goes through elsie-dashboard-helper, which
runs only a fixed list of 'elsie' commands.

Versions

elsie update

install the newest version (elsie update check only looks)

elsie update            install the newest version: one copied into /var/lib/elsieos/updates first,
                        else from the update server ('elsie updates server URL'). It goes into the spare
                        system slot; the next restart starts it, with 3 tries - if it does not start
                        healthily, the version before comes back by itself
elsie update check      only look

elsie updates

where updates come from and what happens by itself: server, auto

elsie updates                       where updates come from, the key they must be signed with,
                                    what the server has, what happens by itself
elsie updates channel [beta | off]  elsieOS's public update channel (beta now; stable from version 1)
elsie updates server URL | off      an update server of your own (a web folder of signed versions)
elsie updates auto off | notify | install [--hour H]
                                    notify (the default): look once a day and announce a new version;
                                    install: also install it and restart into it at hour H when idle

elsie versions

the installed versions

elsie versions          the versions installed in the two system slots (the running one, the spare)

elsie rollback

go back to the version before, and stay there (elsie rollback undo)

elsie rollback          which versions are installed and which one starts
elsie rollback now      restart into the version before this one and keep starting it (for example
                        when something worked better before an update) [--no-reboot]
elsie rollback undo     start the newest installed version again from the next restart
A rollback stays until 'elsie rollback undo' or the next 'elsie update'.

Backups

elsie backup

backups of settings, identity and people's files: add, now, list, recovery, ...

Also: elsie backups

elsie backup - copies of this machine's settings, identity and the things people made, with restic.

    elsie backup                      what is set up, when each destination last worked, what runs next
    elsie backup catalog [ID]         the kinds of destination elsieOS knows (USB drive, another computer,
                                      Backblaze B2, Amazon S3, ...) with prices and how to set each up
    elsie backup add NAME ID [WHERE]  add a destination (asks for its keys, makes the backup password, tests it,
                                      then hands over the recovery file)
    elsie backup remove NAME          stop using a destination (its backups stay where they are)
    elsie backup now [NAME] [--models]    back up now (all destinations, or one; --models copies the models too)
    elsie backup list NAME            the backups a destination holds
    elsie backup restore NAME [ID] --to FOLDER [--only PATH ...] [--models]
                                      copy a backup (or part of it) out into a folder
    elsie backup recovery NAME [--usb | --file PATH]
                                      the recovery file (what a new install needs to read these backups):
                                      shown with a QR code, written to a USB stick or to a file
    elsie backup password NAME        give the backups a new password (if the old one may have been seen)
    elsie backup time HH:MM           when the nightly backup runs (default 03:30)
    elsie backup ping URL | off       a monitoring address (Healthchecks and the like) told after each run
    elsie backup what                 what is backed up and what is left out

Nightly: settings and identity (/etc with the SSH host keys and network settings, Tailscale's identity,
tunnel users, model and app settings), the things people made (ComfyUI's workflows, inputs and outputs) and a
list of the models. Weekly, to destinations set to it: the model files themselves (big; by default only to
your own hardware, never to a cloud). Never: the system itself (it comes back from the published versions)
and logs. Everything is encrypted here before it leaves; without the backup password nobody can read it.

The recovery file (/root/elsieOS-recovery-MACHINE-NAME.txt, and wherever you keep a copy) holds where the
backups are, the key for that place and the backup password. On a new install, 'elsie restore' finds it on a
USB stick by itself, so nothing has to be typed.

elsie restore

make a new install the machine in a backup (finds the recovery file by itself)

elsie restore makes this machine the one in a backup: the same name, network addresses, SSH and
Tailscale identity, settings, models' settings and people's files. Use it on a fresh install (or after a
reset). It needs the recovery file (or the note) kept when the backup was set up:
  elsie restore                finds the recovery file on a USB stick by itself (or takes the recovery code)
  elsie restore --file FILE    from a recovery file copied to this machine
  elsie restore ELSIEOS1:...   from the recovery code (the QR code's text)
  elsie restore 'WHERE'        by hand: WHERE as on the note (e.g. b2:my-bucket:elsieos/mymachine), or usb
It shows what it found and asks before changing anything. Options: --machine NAME (whose backups, if
several), --snapshot ID, --port N (sftp), --no-apps (do not install the apps again), --no-download (do not
download missing models again), --no-reboot, --yes. Model files come back from the backup's model copy if it has
one, else from an old drive in this machine, else they are downloaded again (the same versions, checked).

Setting the machine up (each explains what it changes)

elsie menu

menus for installing, setting up and the status (type a number)

elsie menu - the menus on the machine's own screen: install elsieOS onto a drive, set the machine up, see what it
is doing. Keyboard only: type a number (or letter) and press Enter; b goes back.

    elsie menu              the menus, in any terminal (the machine's monitor after logging in, or SSH)
    menu --welcome          what the machine's monitor shows while nobody has claimed the machine yet - no console
                            password and no SSH key - because a new machine has no other way in at its keyboard.
                            Setting the console password (or adding an SSH key) claims it: from then on the monitor
                            shows the status screen and asks for the password first, and the menus are behind the
                            login ('elsie menu'). Run by the status screen (console) on tty1, never by hand.
    menu --steps-json       the setup steps and their current values, as JSON (for other front ends)

Every choice runs the 'elsie' command a person could type, and shows it, so the menus and the commands never
disagree and the commands can be learnt from the menus.

elsie setup

a guided walk through all of these, in order

elsie setup                      a guided walk through every step below, in order

Every command explains what it changes. Settings live in /etc (the root partition): they survive updates and are part of the machine's backup.

elsie name

the machine's name

elsie name [NAME]                the machine's name on the network

elsie network

address (automatic or fixed)

elsie network                    show the network; automatic | fixed ADDRESS/BITS --gateway G
                                 [--dns A,B] | keep (confirm a change) - a change undoes itself
                                 after 5 minutes unless confirmed, so a wrong address cannot lock
                                 you out | undo (go back at once) | wake-on-lan [on|off]
                                 [--interface PORT] (another machine can start this one)

elsie remote

Tailscale

elsie remote                     Tailscale (private access from anywhere): status | login |
                                 logout | from-old (keep the old system's Tailscale identity)

elsie ssh

keys, tunnels, host keys, port

elsie ssh                        keys allowed to log in: add-key KEY | remove-key N |
                                 tunnel USER [--port 11434,8188] (a key that may only
                                 reach those ports: the model server, ComfyUI) |
                                 host-keys-from-old | port N

elsie server

model server port, who may connect

elsie server                     the model server: port N | allow local home tailscale anywhere

elsie alerts

problems to your phone

elsie alerts                     where problems are reported: pushover USER TOKEN | test | off

elsie timezone

time zone

elsie timezone [ZONE]            the time zone (clock, logs, screen saver)

elsie screensaver

on/off, idle time, clock

elsie screensaver                on | off | idle MINUTES | clock 12|24

elsie console-password

elsie console-password           set the password for logging in at the machine's own keyboard

elsie migrate

what can come over from an old system on another drive

elsie migrate                    what can be brought over from an old system on another drive

elsie ups

a UPS on USB: an alert and a clean shutdown on a power cut

elsie ups [show | setup [--after SECONDS] [--from-old] | off]: a UPS on USB (Network UPS Tools).

elsie boot-other

start another system on this machine's drives (once, or from now on)

elsie boot-other            the other systems this machine's firmware can start (another drive's
                            Linux or Windows, for example the system elsieOS was migrated from)
elsie boot-other N          start system N at the next restart, once; afterwards elsieOS starts again
elsie boot-other N --always start system N from now on (elsieOS stays installed; the other system's
                            firmware settings bring it back)
Changes the firmware's boot settings (efibootmgr); nothing on any drive is changed.

elsie secureboot

Secure Boot here: on or off, through the shim, is the elsieOS key enrolled

Also: elsie secure-boot

elsie secureboot            Secure Boot on this machine: on or off, whether elsieOS started through the
                            shim (Debian's, signed by Microsoft, for PCs that trust only Microsoft's keys)
                            and whether the elsieOS key is enrolled (in the shim's list or the firmware's)
elsie secureboot enroll [CERT]
                            ask the shim to enrol the elsieOS key (or CERT, a new elsieOS release key
                            in DER form) at the next restart: mokutil asks a one-time password, a blue
                            screen confirms it. For a machine that started with Secure Boot off (then
                            switch it on in the firmware), or before a new key signs elsieOS

elsie install

put elsieOS on one of this machine's drives (from a USB stick that runs elsieOS)

elsie install - put elsieOS on one of this machine's drives (run as 'elsie install').

    elsie install                       the drives, what is on them, and what an install would do
    elsie install DRIVE                 install onto DRIVE (its serial, a /dev/disk/by-id/ name or, typed by
                                        hand, its /dev name): shows what would be lost and asks
        --yes                           do not ask (DRIVE must be its serial or by-id name)
        --wipe-other-system             with --yes: also when the drive holds partitions (another system, files)
        --boot-entry / --no-boot-entry  make the firmware start elsieOS from DRIVE first (asked otherwise)
        --copy-ssh-keys                 the SSH keys allowed on this system may log in to the installed one
        --no-carry                      start the installed system fresh (without it, this system's personal
                                        settings and models come along - see below; asked when not --yes)
        --dry-run                       show what would be done, change nothing
    elsie install --json                the drives as JSON (for the menus and the web dashboard; changes nothing)
    elsie install --config FILE         unattended, from an answer file (TOML):
                                            drive = "SERIAL"            (required: the serial, or a by-id name)
                                            wipe_other_system = false
                                            boot_entry = true
                                            copy_ssh_keys = false
                                            carry = true

elsieOS started from a USB stick is the installer: this copies the RUNNING system onto DRIVE - the boot partition
(the boot loader and this version's kernel image), /usr and its verity data into the first system slot, an empty
second slot for updates, an empty root partition and the data partition (the rest of the drive). The installed
system's first start fills root with its own settings, machine id and SSH host keys, as every new elsieOS does.
Everything on DRIVE is erased; the drive elsieOS runs from, and any drive in use, is refused.

What comes along (decided 2026-11-16: the person's settings, never the machine's identity): the console password
(and that the machine is claimed), root's SSH keys, the machine's name, network settings, time zone, update channel
or server, elsieOS's other settings (model server, alerts, screen saver, dashboard password) and the models. Never:
the machine id, SSH host keys, Tailscale's node, the dashboard's certificate, backup destinations, apps (installed
again from the catalogue).