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).
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 settingselsie 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-nicknameselsie 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 catalogueelsie 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 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).