3. CLI reference: ./lawliet

Every command and option of ./lawliet, with examples and what the output means. The script is at the root of the installation directory. It needs only Docker, bash, coreutils and curl on the server.

3.1 Conventions#

• Where. Run it from the installation directory: cd /opt/lawliet-<version>. After an update, use the new directory (the update prints its path).
• Who. As root or with sudo, and always the same account. .env is mode 600.
• Output marks. OK a check passed or a step succeeded; FAIL it did not; ! a warning you should read; a line starting with > begins a new section. Colour is used only on a terminal and never when NO_COLOR is set.
• Exit status. 0 on success, 1 when the command stopped (the last line starting with FAIL says why), 130 when an update was interrupted with Ctrl-C.
• Questions. (y/N) means the default is no; (Y/n) means yes; Enter takes the default. Answers can be piped in. When no answer can be read at all, the default is taken and the command says so. Commands that change things offer --yes for scripts.
• A second deployment on the same host: prefix every command with its project name, for example sudo COMPOSE_PROJECT_NAME=lawliet-staging ./lawliet status.
• Safety. No command except uninstall deletes data. uninstall requires typing DELETE. No command overwrites .env without asking or keeping a copy.

3.2 Summary#

3.3 status#

sudo ./lawliet status

Read-only. Use it first whenever something looks wrong.

What you see: one block per section below, each line marked OK, ! or FAIL, for example OK <url>/health responding and OK Stamped at <revision>.

If no container is running it says Nothing is running. Start it with: ./lawliet start. If it finds Lawliet containers that belong to another project name, it says so instead; do not start a second copy, use that project name.

3.4 start#

sudo ./lawliet start            # everything
sudo ./lawliet start backend    # one service

1. Loads any of the bundle's images that are not loaded yet (each checked against its checksum first).
2. Applies the TLS state recorded in .lawliet.conf to .env.
3. Starts the containers (docker compose up -d), which also recreates any container whose configuration changed. This is how edits to .env take effect.
4. Waits up to 5 minutes for every service to become healthy.
5. Reports a certificate that does not cover an address, if any.
6. On the first start after an update to this version, runs that version's post-update steps once (see Updates).

What you see: the live service list, then OK Running - <console URL>.

If it fails: Not all services are healthy yet. ./lawliet status means the wait ran out; the platform may still finish starting. Check with status and logs backend. The console cannot write .../updates means console uploads of updates will not work; run sudo ./lawliet start.

3.5 stop#

sudo ./lawliet stop             # everything
sudo ./lawliet stop frontend    # one service

Stops containers. Volumes, and therefore your data, are untouched. Agents keep their collected data and send it once the server is back.

What you see: Containers are stopped. Volumes, and therefore your data, are untouched. and OK Stopped. Start again with sudo ./lawliet start (3.4).

3.6 restart#

sudo ./lawliet restart
sudo ./lawliet restart backend

Restarts containers and waits up to 5 minutes for health. A restart does not re-read .env. After changing .env, use sudo ./lawliet start instead.

What you see: OK Restarted. If it fails: Not all services are healthy yet. ./lawliet status - check with status and logs backend.

3.7 logs#

sudo ./lawliet logs backend            # last 200 lines of the backend
sudo ./lawliet logs backend -n 1000    # last 1000 lines
sudo ./lawliet logs nginx -f           # follow; Ctrl-C to stop
sudo ./lawliet logs                    # every service

What you see: the log lines, each prefixed with the service name. With -f it keeps printing until you press Ctrl-C. Logs can contain host names and user names: review them before sending them anywhere, or use diag (3.14), which redacts.

3.8 install#

sudo ./lawliet install

The guided installation. Full walk-through: Installation. To change one setting on a running deployment, use the command for it (passwd, tls, token --rotate, licence), not install.

3.9 backup#

sudo ./lawliet backup                    # into ./backups
sudo ./lawliet backup /mnt/backup-share  # into another directory

Writes three files, all owner-only (mode 600):

What you see: OK Wrote <file> (<size>, <N> tables) for each file, and the restore command. A dump with no tables is discarded and reported as a failure.

Details, scheduling and what is not included: Backup and restore.

3.10 restore#

sudo ./lawliet restore backups/lawliet-20261014-020000.sql.gz

Replaces the whole database with the dump. Asks first (default no).

1. Stops the application (PostgreSQL stays up).
2. Empties the database schema, then loads the dump in one transaction.
3. If a .keys file sits beside the dump and differs from .env, adopts its keys (keeping the previous .env as .env.backup.<timestamp>) and recreates the application. Otherwise restarts it.
4. Puts back the agent artefacts archived beside the dump, if any.

3.11 update#

sudo ./lawliet update /media/usb/lawliet-docker-<new>-<customer>.tar.gz
sudo ./lawliet update /media/usb/lawliet-delta-<old>-<build>-to-<new>-<build>-amd64.tar.gz
sudo ./lawliet update /opt/lawliet-<new>/          # an already unpacked bundle directory
sudo ./lawliet update --staged                     # the bundle the console staged
sudo ./lawliet update <bundle> --no-cert-repair    # skip the certificate check afterwards

Backs up, checks the new bundle's signature, unpacks it beside this directory, loads its images while the current version keeps running, then switches over and verifies. The full procedure, every message and how to go back: Updates, rollback and delta updates.

3.12 rollback#

cd /opt/lawliet-<new>
sudo ./lawliet rollback                     # asks first
sudo ./lawliet rollback --yes               # no question
sudo ./lawliet rollback --to /opt/lawliet-<old> --backup /opt/lawliet-<old>/backups/lawliet-<time>.sql.gz

Returns to the version this one was updated from, database included. Data written since the update is saved first and not lost. Full procedure: Rolling back.

3.13 doctor#

sudo ./lawliet doctor            # report and write a support file
sudo ./lawliet doctor --fix      # offer each safe fix, one question each
sudo ./lawliet doctor --fix --yes
sudo ./lawliet doctor --help

Checks services, images, TLS state, certificate, TRUSTED_HOSTS, clock, disk, licence, backups and leftovers, and lists each finding with either a safe fix or the command to run. Full list of findings and fixes: Doctor, diag and support.

3.14 diag#

sudo ./lawliet diag
sudo ./lawliet diag --since 24h --output /media/usb

Writes one redacted archive lawliet-diag-<host>-<UTC time>.tar.gz (mode 600) to send to the vendor. It refuses to write the archive if its self-check finds a secret in it.

Contents and redaction: Doctor, diag and support.

3.15 token#

sudo ./lawliet token             # show the enrolment secret and install commands
sudo ./lawliet token --rotate    # replace the enrolment secret

Without options it prints the enrolment secret and a one-line install command each for Linux, macOS and Windows (PowerShell as Administrator), correct for this deployment:

• with a self-signed certificate, the commands include --cacert/--ca-cert (-CaCert on Windows) pointing at /path/to/lawliet-server.pem; export the file first with sudo ./lawliet tls --export;
• with TLS off, they install over plain HTTP and carry --insecure (-Insecure).

The same commands are in the console under Environment > Install agent. Installing agents: Agents overview.

--rotate asks first (default no), writes a new secret to .env, restarts the backend and prints the new secret. Agents already enrolled are not affected; they use their own per-agent token. Only new installations need the new commands. Rotate when the secret has been shared more widely than intended.

What you see: the secret, then the Linux, macOS and Windows commands. Treat the output as a secret: anyone with it can enrol a host.

No enrolment secret is set - every agent registration will be refused with 401 means AGENT_REGISTRATION_SECRET is empty. Fix with sudo ./lawliet token --rotate.

3.16 agent-package#

sudo ./lawliet agent-package --os linux --arch amd64 --hosts 50 --days 7 --label "Plant floor"
sudo ./lawliet agent-package --os windows
sudo ./lawliet agent-package --os windows --gpo --hosts 400
sudo ./lawliet agent-package --help

Builds an offline agent package for hosts that cannot download from the server. It carries the agent, its installer, the certificate when it is self-signed, and a new enrolment code that expires (never the enrolment secret).

What you see: Written: <path>, the enrolment code number, hosts, expiry, server, the certificate inside, and Package SHA-256. Compare that value with the copied file on the target host before installing. Then the commands to run on each host.

The file holds an enrolment code: treat it like a password and delete it when done. A lost code can be revoked in the console under Environment > Install agent > Offline package. ./lawliet doctor --fix offers to remove expired packages from the installation directory. Installing from a package: Linux agents, Windows agents.

The CLI is root on the server, so this needs no console approval. The code is recorded in the audit trail as made through the CLI.

3.17 passwd#

sudo ./lawliet passwd

The recovery path for a locked-out administrator. It:

1. Asks for a new password twice (12 to 128 characters, not a known default).
2. Writes it to .env as LAWLIET_ADMIN_PASSWORD.
3. If the administrator account exists: Also change it on the existing '<user>' account now? (default yes). Sets the password, re-activates the account, and clears the forced password change.
4. If two-factor is on for that account: Turn two-factor OFF for this account? (default no). Answer yes when the authenticator is lost; enrol it again after signing in.
5. Restart the backend now? (default yes).

It acts on the account named by LAWLIET_ADMIN_USERNAME in .env (the install-time administrator). For other users see 15.2 A user forgot their password.

Risk: anyone with root on the server can take over the administrator account this way. That is why shell access must be restricted (Security hardening).

3.18 tls (inspect, replace, export)#

sudo ./lawliet tls                     # show subject and expiry, offer to replace
sudo ./lawliet tls --export            # write ./lawliet-server.pem for agent hosts
sudo ./lawliet tls --export /tmp/srv.pem

tls without options shows the certificate's subject and expiry (warning within 30 days) and asks Replace the certificate? (default no). Yes asks for the new certificate and key paths and installs them safely.

Procedures: TLS and certificates.

3.19 tls on, off, status, repair, cancel#

sudo ./lawliet tls status
sudo ./lawliet tls off          # asks; --yes to skip
sudo ./lawliet tls on           # asks the follow-up questions; --yes accepts them
sudo ./lawliet tls repair       # re-issue a self-signed certificate that misses an address or expires soon
sudo ./lawliet tls repair --yes --timeout 1800 --ack 90
sudo ./lawliet tls cancel       # withdraw a certificate handed to agents but not switched to

Every step, message and risk: TLS and certificates.

3.20 licence#

sudo ./lawliet licence                      # show the licence and fingerprint
sudo ./lawliet licence /path/to/customer.key
sudo ./lawliet licence LAWLIET-...

Without an argument it shows: licence type and organisation, valid until (days left), issue date, whether it is bound to this installation, where it was loaded from, and the installation fingerprint to send to your vendor.

With a key or a file, in order:

1. Checks the key with the server's own validator. Nothing changes if it is refused.
2. Refuses a key issued before the licence in use.
3. Writes LAWLIET_LICENSE_KEY to .env, keeping the previous file as .env.backup.<timestamp>.
4. Recreates the backend so it reads the new value, and waits for health.
5. Confirms Licence in effect.

No console approval applies. See Installation, step 2.10.

3.21 uninstall#

sudo ./lawliet uninstall

Deletes the containers and every data volume: the database, collected logs, the hosted agent artefacts and the installation fingerprint. After it, this server is a new installation that needs a new licence.

1. Take a final backup first? (default yes). If the backup fails it asks whether to delete anyway (default no).
2. Type DELETE in capitals to confirm. Anything else stops it.

.env and ./backups are left in place. To only stop the platform, use stop.

Rollback: only by installing again and restoring the final backup (Backup and restore). A licence bound to the old fingerprint does not work on the new installation.

3.22 version and help#

./lawliet version     # Lawliet 1.5.13.s
./lawliet help        # the command list, and this deployment's console URL

What you see: Lawliet <version>, or the command list followed by Console and Documentation. Neither needs root. An unknown command answers Unknown command: <name> and Try: ./lawliet help.

3.23 Files the CLI reads and writes#

All paths are relative to the installation directory.