istok ui — Istok

istok ui serves the web UI built into the Istok binary and manages it as a background service on Linux and macOS. For what the UI shows, see the Web UI guide; for setting up the service step by step, see Updates and running the UI as a service.

Commands

Command	Purpose
`serve`	Serve the web UI in the foreground. This is the default.
`service install`	Create or update the service, enable it, and (re)start it.
`service uninstall`	Stop and disable the service and remove its file.
`service start`	Start the service.
`service stop`	Stop the service.
`service restart`	Restart the service.
`service status`	Show the service status.

Serve the UI

istok ui

is the same as:

istok ui serve

Istok listens on 127.0.0.1, prints the address, and opens it in your default browser:

Istok UI: http://127.0.0.1:7700/
Press Ctrl+C to stop.

If no browser can be opened, Istok prints a note and keeps serving; open the address manually.

Flags:

Flag	Default	Purpose
`--port`	`7700`	Loopback port. `0` picks a free port. Also `ISTOK_UI_PORT`.
`--no-open`		Print the address without opening a browser.
`--database PATH`		Path to the SQLite database. Also `ISTOK_DATABASE`.

For example:

istok ui --port 7800 --no-open

If the port is already in use, the command fails and suggests choosing another one with --port.

The UI is reachable only from the local machine. It has no login or token; see the Web UI guide for what this protects against and what it does not.

Run as a service

istok ui service runs the UI as a per-user background service. No root access is needed.

System	Service manager	Service	File
Linux	systemd (`systemctl --user`)	`istok-ui.service`	`${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/istok-ui.service`
macOS	launchd (`launchctl`, domain `gui/<uid>`)	`sh.istok.ui`	`~/Library/LaunchAgents/sh.istok.ui.plist`

On other systems, or without systemctl or launchctl, the command reports that it is not supported; run istok ui directly instead.

The file is regenerated on every install, so do not edit it by hand.

Install

istok ui service install

install writes the service file, loads or reloads the service, and (re)starts it. It prints the file path, the binary the service runs, and the address:

Istok UI: http://127.0.0.1:7700/

The service runs the absolute path of the istok binary you used for install, with ui --no-open and the chosen port.

Flags:

Flag	Default	Purpose
`--port`	`7700`	Loopback port the service listens on. Also `ISTOK_UI_PORT`.
`--database PATH`		Path to the SQLite database, recorded in the service file. Also `ISTOK_DATABASE`.

The service does not inherit your shell environment. If you use a custom database, pass it to install (or have ISTOK_DATABASE set when you run it) so the absolute path is written into the service file.

Run install again to change the port or database, or to move the service to a different istok binary.

Restarts and logs

The service starts again after a crash. On Linux, systemd restarts it after 2 seconds; read the log with journalctl --user -u istok-ui. On macOS, launchd restarts it after about 10 seconds and starts it at every login; the log is ~/Library/Logs/istok/ui.log.

Keep it running after logout (Linux)

systemd stops user services when your last session ends unless lingering is enabled for your user:

loginctl enable-linger

Control the service

istok ui service status
istok ui service stop
istok ui service start
istok ui service restart

On Linux these commands call systemctl --user for istok-ui.service. An inactive service is reported by status without being treated as an error.

On macOS they call launchctl: start and restart use kickstart, status shows launchctl print. stop unloads the agent (bootout), because launchd would otherwise start the stopped UI again; it loads again on start or at your next login.

Uninstall

istok ui service uninstall

This stops the service and removes its file. On Linux it also disables the unit and reloads systemd; on macOS it unloads the agent.

Updates

After a successful istok update, Istok restarts the service if all of these are true:

the service is installed;
the service is active;
the service runs the binary that was just updated.

When the restart happens, istok update prints:

Restarted the web UI service on the new binary.

If the restart fails, the update still counts as successful and Istok prints a warning. Restart it yourself with istok ui service restart.