Skip to content
eternego / docs

CLI

This section documents the eternego command — every subcommand, every flag, exactly as index.py defines them. The CLI is how you start her, stop her, register her as a background service, follow her logs, and prepare a model from a terminal. The dashboard and the HTTP API drive a running persona; the CLI starts and supervises the process that serves her.

The eternego command

There are three ways the same command reaches you, depending on how Eternego was installed:

  • Installed app — the macOS .app, the Windows .exe, and the Linux .AppImage are wrappers around eternego launch. Opening the app from Finder, the Start Menu, or by running the AppImage is the same as running eternego launch: it starts the daemon and opens the dashboard in your browser. (On macOS, when the bundle is opened from Finder with no arguments, the wrapper sets ETERNEGO_LAUNCH_FROM_BUNDLE=1 and the entry point treats it as launch.)
  • Background service — when you register her with eternego service start, the OS service manager (systemd / launchd / Scheduled Task) runs eternego daemon for you on login and keeps it alive across reboots.
  • From source — a contributor clone runs the same entry point as python index.py <command>. Everywhere this section writes eternego <command>, python index.py <command> is equivalent. The installer also drops an eternego launcher on your PATH (~/.local/bin/eternego on Linux/macOS; the venv Scripts directory on Windows) so the short form works after a source install too.
usage: eternego [-h] [--debug] [-v] [--port PORT] [--host HOST] COMMAND ...

Eternego AI persona manager

Run eternego with no command to print this help. Run eternego <command> --help for any subcommand's own flags.

Global flags

These flags belong to the top-level parser, so they come before the command:

eternego --debug --port 8080 daemon
Flag Type Default Effect
--debug switch off Enables debug-level logging and writes the signal log file (eternego-signals-<date>.log). In debug mode each persona also gets her own per-persona log file (eternego-<persona_id>-<date>.log).
-v, --verbose count 0 Increases console output. Repeatable — -v, -vv, -vvv each raise the level (see What -v controls).
--port PORT int 5000 Web server port. Also settable with the WEB_PORT environment variable. If the port is already in use, the daemon picks the next free port and prints Port <requested> was in use; using <chosen> instead. — this applies to both daemon and launch (which runs the same loop).
--host HOST string 127.0.0.1 Web server host (loopback by default). Also settable with the WEB_HOST environment variable.

The default port is 5000 and the default host is 127.0.0.1 — both come from config/web.py (WEB_PORT / WEB_HOST). There is no authentication; the daemon is meant to be reached only from the same machine. See API → Base URL.

Which commands honor the global flags

The global flags configure logging and the web server. The logging flags (--debug, -v) take effect for every command that initializes the application: daemon, launch, and env (each calls the shared bootstrap that wires up logging). The web-server flags (--port, --host) only matter for the commands that actually bind a server — daemon and launch; env accepts them but never starts a server, so they have no effect there. The service and uninstall commands don't initialize the application at all — they hand off to the OS service manager or a removal routine — so a top-level --debug / -v placed in front of them is accepted by the parser but has no effect. To run the background service in debug mode, use the --debug / -v flags on service start instead; those get forwarded onto the eternego daemon command line the service runs.

What -v controls

Logging always goes to the daily log file at ~/.eternego/logs/eternego-<date>.log (debug-level lines are written to it only when --debug is set). The verbosity flag controls what is also echoed to your console:

Level Logs echoed to console Signals echoed to console
0 (none) nothing nothing
-v nothing Plans (Tick) and Events (Tock) only
-vv INFO and above all signals
-vvv everything (incl. DEBUG) all signals

(Plan and Event are the cognitive signals a stage dispatches on entry and exit. Other signals — proposals and broadcasts — appear from -vv up.)

The commands at a glance

Command What it does
launch Start the daemon and open the dashboard in your browser. What the installed app runs.
daemon Run the daemon in the foreground. What the OS service runs; also the dev run loop.
service Register / control the background service: start, stop, restart, status, logs.
uninstall Remove the service and the installed source. Leaves ~/.eternego (her data) untouched.
env Check a model is reachable (check) or pull / verify one (prepare).