teabot/docs/run.md

teabot run

Runs the daemon in the foreground. It polls the configured repos on poll_interval and dispatches Claude sessions. This is the command the systemd user unit executes.

teabot run [flags]

Flags

Flag	Default	Description
--once	false	Run a single poll cycle then exit. Blocks until every job dispatched during the cycle finishes — ideal for testing.
--log-json	false	Emit structured JSON logs instead of text.
--log-level	info	debug, info, warn, or error.
-c, --config	~/.config/teabot/config.yaml	Config file path (inherited from the root command).

Logs go to stderr (captured by the systemd journal). teabot handles SIGINT/ SIGTERM by stopping the poll loop and waiting for in-flight jobs to finish before exiting.

Examples

# One cycle, verbose, to see what would be dispatched.
teabot run --once --log-level debug

# Foreground daemon with JSON logs.
teabot run --log-json

systemd (user service)

The RPM installs a user unit at /usr/lib/systemd/user/teabot.service.

systemctl --user daemon-reload
systemctl --user enable --now teabot
journalctl --user -u teabot -f

Because it is a user service it runs as your login user, so it inherits your Docker access and your ~/.claude credentials. To keep it running when you are not logged in, enable lingering:

loginctl enable-linger "$USER"

Requirements at runtime

• docker on PATH and usable by the running user.
• The configured job_image pullable from the registry.
• Each personality's tea config file present and readable.
• Claude credentials available (subscription ~/.claude or an anthropic_api_key in the config).