Skip to content

cli.md

Latest commit

 

History

History
233 lines (162 loc) · 7.71 KB

cli.md

File metadata and controls

233 lines (162 loc) · 7.71 KB

CLI Reference

Gula provides a simple command-line interface.

Usage

gula [OPTIONS] [COMMAND]

Commands

run (default)

Start the process supervisor. This is the default if no command is specified.

gula run --config config/gula.yaml

Exit codes:

  • 0 — All processes completed successfully, or a signal-initiated shutdown (SIGTERM/SIGINT/SIGHUP/SIGQUIT) stopped otherwise-healthy processes cleanly.
  • 1 — One or more processes failed (non-zero exit, timeout, readiness timeout, or policy violation), including failures observed before a later shutdown signal.

validate

Validate configuration files without starting any processes.

gula validate --config config/gula.yaml --sys-config config/gula_config.yaml

doctor

Probe the host environment and report whether gula will run cleanly. doctor does not connect to a running supervisor; it reads from /proc, runs syscall probes, and (optionally) parses the config file at --config. When config files are available, doctor validates both the process config (--config) and system config (--sys-config). It also checks whether the configured scheduling controls require elevated capabilities: CAP_SYS_NICE for negative niceness, and CAP_SYS_ADMIN for ionice.class: realtime. It warns if the current process lacks a required capability or if the capability state cannot be determined.

gula doctor
gula doctor --config config/gula.yaml --sys-config config/gula_config.yaml
gula doctor --format json | jq .overall

Exit codes:

  • 0 — every check passed
  • 1 — at least one warning (gula will run, with caveats)
  • 2 — at least one failure (gula cannot reasonably run)

init

Bootstrap a starter gula.yaml from a built-in template. Interactive by default; pass --non-interactive for CI / scripted use.

# Interactive wizard
gula init

# Non-interactive: pick a template and force-overwrite
gula init --non-interactive --template minimal --output config/gula.yaml --force

Available templates: minimal, edge. The generated file is validated against the same schema gula validate uses, so a successful init always produces a loadable process config. If config/gula_config.yaml does not already exist, init also writes the starter system config there; pass --system-output to choose a different path. Files are written through a same-directory temporary file and atomic rename, so concurrent or interrupted writes do not leave a half-written YAML at the target path.

status

Connect to the running supervisor's control plane and render process state. It discovers the local runtime endpoint automatically; it never spawns a supervisor itself.

# One-shot table view
gula status

# Watch mode at 500 ms cadence
gula status --watch 500

# Watch mode with machine-readable newline-delimited JSON
gula status --watch 500 --format json

# Single process, JSON, for scripting
gula status --name worker --format json

Watch mode exits cleanly on Ctrl-C or SIGTERM. Table watch mode clears the terminal between polls; JSON watch mode emits one compact JSON value per poll.

Supervisor discovery order (first hit wins):

  1. Hidden/advanced socket overrides (--socket <PATH> or $GULA_CONTROL_SOCKET)
  2. Runtime endpoint ($GULA_RUNTIME_DIR/control.sock, /run/gula, $XDG_RUNTIME_DIR/gula, or /tmp/gula-$UID)
  3. Legacy <config.logs_dir>/gula.sock from --config
  4. Legacy ./logs/gula.sock

For modern supervisors, --config is not needed for status; it is only used as a legacy socket fallback. status exits with code 2 when no running supervisor can be located or reached.

tui

Open the interactive terminal dashboard for a running supervisor. It discovers the local runtime endpoint the same way status does and never starts a supervisor itself.

gula tui
gula tui --tick-ms 250

The dashboard shows process state, recent CPU/memory/core samples, selected process details, recent buffered stdout/stderr lines, and pending control-plane operations. It can start, stop, and restart the selected process through the same state-gated operation flow as the dedicated CLI commands.

Use log_config.ring_buffer_size for processes whose recent logs should appear in the dashboard. Without a ring buffer, the process still appears in the table and details view, but the log pane has no buffered lines to show. See the Terminal Dashboard page for key bindings and log behavior.

start, stop, restart

Send a typed process-control request to the running supervisor.

gula stop worker
gula restart worker
gula start worker

# Return after the supervisor accepts the operation
gula restart worker --no-wait

# Machine-readable operation record
gula stop worker --no-wait --format json

By default these commands wait until the operation reaches succeeded or failed. Use --timeout-ms and --poll-ms when a process has unusually slow shutdown or startup behavior.

Exit codes:

  • 0 — connected and rendered
  • 1 — supervisor returned an error or unexpected response
  • 2 — could not locate / connect to a running supervisor
  • 3 — supervisor responded with an incompatible API version

Options

-c, --config <FILE>

Path to the process configuration file.

  • Default: config/gula.yaml
  • Example: gula --config /etc/gula/prod.yaml
  • Used by: run, validate, doctor, and legacy socket discovery for status, start, stop, and restart
  • Also used by: legacy socket discovery for tui
  • Not used by: init; use --output instead

--sys-config <FILE>

Path to the system configuration file. This file controls supervisor-level behavior such as the cleanup timeout after sending termination signals. See Configuration — System Configuration for details.

  • Default: config/gula_config.yaml
  • Used by: run, validate, and doctor
  • Not used by: init, status, tui, start, stop, or restart

-l, --log-level <LEVEL>

Set the default logging level. This is the floor; per-target overrides via RUST_LOG (see below) can raise individual modules above it.

  • Default: info
  • Values: off, error, warn, info, debug, trace

-h, --help

Print help information.

-V, --version

Print version information.

Environment Variables

GULA_RUNTIME_DIR

Overrides the runtime directory used by gula run and by operator clients such as gula status, gula stop, and gula restart. The supervisor creates control.sock, supervisor.lock, and supervisor.json inside this directory. The path must be absolute. Use this for tests, development shells, or deployments that want an explicit runtime path.

GULA_CONTROL_SOCKET

Advanced escape hatch for clients only. When set, operator commands connect to this exact Unix-domain socket instead of discovering the runtime endpoint.

RUST_LOG

Gula uses the tracing ecosystem and parses RUST_LOG as an EnvFilter directive. The CLI's --log-level value sets the default directive; any RUST_LOG value layered on top can target individual modules at a different level without raising the global floor.

Examples:

# Trace just the central monitor; everything else stays at info.
RUST_LOG=gula::monitor=trace gula run

# Quiet most of the supervisor but keep policy decisions verbose.
RUST_LOG=warn,gula::process::policy=debug gula run

# Combine with --log-level: --log-level sets the baseline, RUST_LOG layers on.
RUST_LOG=gula::process::execution=trace gula --log-level warn run

If RUST_LOG is not valid Unicode or contains an unparseable directive, Gula fails fast with an error before spawning any processes.