botmux 文档
  • English

      • CLI Commands

      Manage the daemon and sessions from the terminal.

      CommandDescription
      botmux setupInteractive configuration (first run / add / edit / delete a bot)
      botmux start [--companion-secret-file <path> --companion-bot <appId>]Start the daemon. Supplying both companion options enables the closed local API for exactly one isolated test Bot; see Local Companion API
      botmux stopStop the daemon
      botmux restart [--companion-secret-file <path> --companion-bot <appId>]Restart the daemon and restore active sessions; accepts the same closed Companion API options as start
      botmux logs [--lines N]View logs
      botmux statusView daemon status
      botmux upgradeUpgrade to the latest version
      botmux list (alias ls)Interactively list active sessions; select a managed tmux / ZMX session and press Enter to attach (use --plain in scripts)
      botmux delete <id> (aliases del/rm)Close the specified session, with ID prefix matching
      botmux delete allClose all active sessions
      botmux delete stoppedClean up zombie sessions whose processes have exited
      botmux dashboard [current|rotate]Get the current Dashboard login URL, creating the first token if absent; rotate explicitly replaces an existing token

      When the daemon is online, botmux delete first asks the owning daemon to run the same lifecycle teardown as /close: evict the in-memory active session, persist the closed state, and clean up the worker, backend, and subscriptions. The local fallback is used only when the owning daemon is confirmed offline. If an online daemon rejects the request or IPC fails, the command fails without a local hard kill.

      Auto-Start on Boot

      botmux autostart enable   # Register (macOS launchd / Linux user systemd, no sudo needed)
botmux autostart disable  # Unregister
botmux autostart status   # Check status
      • macOS: writes ~/Library/LaunchAgents/com.botmux.daemon.plist and loads it with launchctl bootstrap.
      • Linux: writes ~/.config/systemd/user/botmux.service and runs systemctl --user enable --now.
        • On servers / headless environments, logging out stops the service; to keep it running across logout, run sudo loginctl enable-linger <username>.
      • The node/cli.js paths in the unit file come from the current process.execPath; after switching versions with nvm/fnm, just run enable once to rewrite them (start/restart also auto-detect path changes and refresh in place).
      • enable/disable only manage the auto-start hook and don't touch a running daemon — avoiding the "I just wanted to turn off auto-start but it killed the service too" problem.

      In-Session Subcommands (for the CLI agent)

      Session info is inferred automatically from ancestor-process markers, so the agent can call these directly:

      CommandDescription
      botmux send [content]Send a message to the current topic (stdin / heredoc / --content-file; --images/--files/--videos/--card-file/--card-json/--mention)
      botmux card patch --message-id <om_xxx> (--card-file <path> | --card-json <json>)Update a previously sent custom card in place (no new message; the messageId comes from the send output)
      botmux bots listList the bots in the current group (including open_id); --scope team [--team <id>] discovers same-team, opted-in agents across machines (by specialty)
      botmux bots invite --chat <chatId> --team <id> --agent <appId>...Add same-team agents + their owners into a group you're already in (auto-adds the platform app first if absent)
      botmux history [--limit N]Pull the session history (JSON)
      botmux quoted <message_id>Pull a single quoted message (JSON)
      botmux schedule add/list/update/remove/pause/resume/runManage scheduled tasks
      botmux session rename "<title>"Rename the current session's botmux canonical title (the session is auto-detected; no --session-id or any way to target another session). Dashboard and the /sessions list update instantly, and the CLI-native session name is synced best-effort. The Lark group name and omt topic name are unchanged (no platform API for topic titles). Recommended shape "type | subject", up to 200 characters
      botmux chat rename <new group name> [--proactive]Rename the Lark group that hosts the current session (in a topic group this is the whole oc_ group, visible across every topic and to every member). --proactive is for agent-initiated renames on a phase change, with a 10-minute debounce