Operator commands

Run them in the project directory as the same user that runs the bot. Login, model selection, pause / resume and statistics read only dataDir and each persona's provider/model from jingmei.config.json and need no bot tokens; update needs neither configuration nor tokens. bun run jingmei --help lists every command.

Command	What it does
bun run jingmei	Interactive menu (before a config exists it offers only "Set up", i.e. init): status, check install, update, switch model, pause / resume, sign in, sign out; each action returns to the menu until you pick Exit
bun run jingmei init	First-run wizard: creates jingmei.config.json, .env (mode 0600) and a persona file, verifying bot tokens live; refuses to run when a config exists and needs an interactive terminal
bun run jingmei start	Run the bot in the foreground, same as bun run start
bun run update / bun run jingmei update	Fast-forward the current branch from its upstream, install locked dependencies, check TypeScript, then request a graceful reload of any running bot; when stopped, only updates files
bun run jingmei doctor	Read-only self-check: config, the run_js sandbox, models and credentials, Discord / Telegram tokens and permissions (Message Content Intent, privacy mode, group ids), and ffmpeg, fonts, sqlite-vec and the embedding cache for the features you enabled. One OK / WARN / FAIL line each with a one-line fix hint; exits non-zero on any FAIL. Never prints a token
bun run jingmei telemetry	Print exactly what this instance would report next and whether it is on; see Usage statistics. Needs the full config
bun run jingmei login [provider] / logout [provider]	Sign in with OAuth / remove a stored credential; signing in refreshes that provider's model list
bun run jingmei model [provider/model|default] [--persona <id>]	Show and switch a persona's chat model; without a model it refreshes the model lists and opens a picker
bun run jingmei pause / resume	Pause / resume
bun run jingmei stats	Status and current uptime, total runtime and number of starts, replies, and message / group / member / topic / celebration totals
nice -n 10 bun scripts/backfill-message-index.ts [delayMs]	Index messages stored before the upgrade (keywords + vectors), newest first, 100 ms between messages by default; safe to interrupt and rerun, indexed rows are skipped. Run it once after deploying the new version; new messages are indexed automatically. See docs/deploy.md (Chinese)

• Pause: the bot stays online and keeps storing messages, but does not reply, react, update member memory or topics, or send celebrations, and makes no reply-model calls; administrator manual compaction can still call a model. It applies to a running bot immediately without a restart, and survives restarts until resume. Messages received while paused are only stored and written to no session (after resuming, when a character is triggered they may enter its new session with the recent window like any other untriggered message); greetings due that day go out after resuming. To actually stop the process, use systemctl --user stop pi-discord-agent or Ctrl+C.

• Status: the bot writes a heartbeat every minute; with no heartbeat for two minutes it counts as stopped (including crashes). Replies are counted from the release that introduced this command; message and other totals cover all history.

• Switch model: only the CLI on the server can switch models; there is no chat command for it. The choice is stored in the database, the running bot moves each channel over before its next reply without a restart, and it survives restarts. default restores provider/model from jingmei.config.json. reasoningEffort is kept and Pi clamps it when the new model does not support it. To use another provider, login first or put its API key in the service environment. If the bot cannot find the chosen model (for example its provider was removed), it logs model_override_unavailable and keeps using the configured model. A switch invalidates the provider's prefix cache once.

• Context and conversation segments: each character's channel session uses the model's own contextWindow (for example Gemini's 1M), without a shared cap. In normal operation a segment is replaced at the next trigger once 5 minutes pass without a reply, more than 30 messages accumulate, or the session exceeds 40,000 tokens, so reply input stays small and does not depend on compaction. Pi still provides near-limit auto-compaction (window minus 16,384 tokens) and provider overflow recovery; administrators can still use /compact; /context shows current usage, the window size in messages and the segment limits. Compaction retains about 15–20k real recent tokens (Pi's character estimate undercounts Chinese about fivefold, so the kept tail remains 3,000 estimated tokens); within a segment history grows only at the end, helping prefix caches.

• Hot updates: every entrypoint (including the existing systemd service) watches jingmei.config.json, .env and configured persona files, including paths outside the project. Filesystem events request a reload after a 500ms debounce, with no idle file scanning; use update for code changes. The supervisor validates configuration, waits for current conversations and background writes, then closes the old worker's database before starting its replacement. Platforms briefly reconnect. Invalid configuration logs reload_rejected, keeps the old worker and retries after repairs. Runtime problems such as invalid tokens or unavailable models can still prevent startup; inspect startup_failed. Tracked local edits, divergent history, failed installs or failed type checks stop update without requesting a reload; fetched code is not rolled back automatically, so fix the cause and retry. The first upgrade needs one manual restart to activate the supervisor; see deployment updates.