Terminal User Interface (TUI)
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal User Interface (TUI) provides a command-line environment for managing the OneBots gateway, configuring platform accounts, and installing extensions. It functions as both a standalone CLI tool and an integrated component within the Web management console, allowing users to execute maintenance commands and manage immutable runtime generations without direct configuration file editing.
Sources: README.en.md:118-125, AGENTS.md:104-108
TUI Invocation and Command Management
The TUI is the primary interface for administrative tasks when a full graphical environment is not required or available. It handles initialization, setup, and configuration of the OneBots environment through specific command flags.
Invocation Logic
The isDirectControlTuiInvocation function determines if the program should start in TUI mode. It checks for specific arguments including ui, tui, setup, --setup, --configure, or --data-dir. If the environment is interactive and these flags are present, the system enters the TUI management entry point.
Sources: packages/onebots/src/control/tui-command.spec.ts:18-24
Command Responsibilities
- Setup (
--setup): Triggers theControlClientinstallation wizard. This process fetches the extension catalog, generates an installation plan, and manages dependencies. - Configuration (
--configure): Opens the configuration draft wizard. It allows users to modify account settings and protocol exports before applying them to the live gateway. - Service Requirement: The TUI requires the management service (
onebots serve) to be running in another terminal. If the service is offline, the TUI rejects connection attempts to prevent silent failures.
Sources: packages/onebots/src/control/tui-command.spec.ts:48-60, packages/onebots/src/control/tui-command.spec.ts:33-40
This diagram illustrates the decision path taken by the CLI to determine whether to launch the TUI or the standard gateway process.
Sources: packages/onebots/src/control/tui-command.spec.ts:18-74
Web-Integrated Terminal
OneBots includes a web-based terminal view that mirrors TUI capabilities within the browser. This allows remote maintenance of the host workspace through a secure, exclusive session.
Technical Implementation
The web terminal utilizes xterm.js for rendering and a FitAddon to handle responsive resizing. It communicates with the backend via WebSockets to transmit input and receive shell output. Each time a user enters the Terminal view, the system creates a new exclusive session.
Sources: packages/web/src/views/TerminalView.vue:145-165
Connection Lifecycle
- Status Check: The client calls
/api/control/terminal/statusto verify if terminal components are available on the host device. - Ticket Acquisition: The client requests a temporary session ticket via a
POSTrequest to/api/control/terminal/ticket. - WebSocket Handshake: The client opens a WebSocket connection using the ticket. It verifies the management service identity (Instance ID and Version) before establishing the "ready" state.
- Interaction: Data typed in the terminal is sent as
inputpayloads; the backend streamsoutputpayloads back to the terminal instance.
This sequence shows the multi-step handshake required to establish a secure terminal session within the Web UI.
Sources: packages/web/src/views/TerminalView.vue:50-100
Configuration and Extension Management
The TUI serves as the primary gateway for the immutable installation flow. Unlike legacy systems that allow runtime plugin loading via CLI flags, OneBots requires explicit plans and activation via the TUI or Web UI.
Key Management Features
| Feature | TUI Command / Path | Description |
|---|---|---|
| Environment Diagnosis | onebots doctor | Checks components and environment health. |
| Installation Plan | --setup | Selects adapters and protocols, verifies peer dependencies. |
| Runtime Update | update | Plans and installs gateway runtime updates. |
| Service Control | install / start / status | Installs or manages the OS service (User/System level). |
| Auth Bootstrap | auth bootstrap | Generates a device code for browser pairing. |
Sources: README.en.md:110-130, AGENTS.md:170-175, packages/onebots/src/control/tui-command.spec.ts:61-75
Security Constraints
- Local Access Only: The terminal is typically restricted to the device where the service is running for security reasons.
- Ticket Expiry: Sessions are tied to specific tickets that expire or close when the page is navigated away.
- Identity Validation: The terminal connection will fail if the
instanceIdorversiondoes not match the management service that issued the ticket.
Sources: packages/web/src/views/TerminalView.vue:64-70, packages/web/src/views/TerminalView.vue:90-95
Conclusion
The TUI is a robust administrative layer that bridges command-line efficiency with a modern management architecture. By enforcing a structured lifecycle for installations and configurations, it ensures that the OneBots gateway remains stable even when the management interface is actively performing maintenance tasks or updates.