CLI & Control Service

Relevant source files

The following files were used as context for generating this wiki page:

• packages/onebots/src/cli/command-application.ts
• packages/onebots/src/control/command.ts
• packages/onebots/src/cli/commands/run.tsx
• packages/onebots/package.json
• packages/onebots/src/cli.test.ts
• packages/onebots/src/control/tui-command.spec.ts
• packages/core/src/app-observability.ts
• AGENTS.md

OneBots provides a unified Command Line Interface (CLI) and Control Service to manage the bot gateway lifecycle. The CLI acts as the primary entry point for users to install, configure, and monitor the gateway, while the Control Service provides the underlying API for management operations.

Sources: packages/onebots/package.json:7-9, AGENTS.md:12-16

Overview and Architecture

The OneBots management layer separates the long-running management service from the independent gateway processes. This architecture ensures that the management console remains available even if the gateway fails or stops. The CLI leverages a ControlClient to communicate with the management service via HTTP and WebSocket APIs.

Sources: AGENTS.md:12-16, packages/onebots/src/control/tui-command.spec.ts:8-15

Component Interaction Flow

The following diagram illustrates how user input through the CLI or TUI interacts with the Control Service and the Gateway Runtime.

CLI Command System

The CLI uses the Pastel and Ink frameworks to provide a reactive, React-based terminal interface. It automatically detects if the environment is a TTY (interactive terminal) to decide between launching the TUI or the standard foreground gateway process.

Sources: packages/onebots/package.json:61-63, packages/onebots/src/cli.test.ts:24-35

Core CLI Commands

Command	Purpose
install	Installs dependencies and registers the management service.
start	Launches the management service and gateway.
status	Checks the health and readiness of the gateway and adapters.
ui	Launches the interactive Terminal User Interface (TUI).
auth	Manages authentication, including device code bootstrapping.
run	Starts the gateway in the foreground (default in non-TTY).
doctor	Diagnoses the environment and installed manager/gateway.

Sources: README.en.md:92-120, packages/onebots/src/cli.test.ts:24-35, packages/onebots/src/control/tui-command.spec.ts:83-95

Runtime Options

Commands can be modified by several standard flags that control how adapters and protocols are loaded into the runtime.

Flag	Name	Description
-r	register	Registers specific platform adapters (e.g., qq, mock).
-p	protocol	Enables specific output protocols (e.g., onebot-v11).
-t	target	Sets the application framework target (e.g., zhin).
-c	config	Specifies the path to the config.yaml file.

Sources: packages/onebots/src/cli.test.ts:40-45, packages/onebots/src/cli.test.ts:161-166

Control Service and TUI Logic

The TUI provides a guided experience for installation and configuration. It communicates with the backend via the ControlClient, which issues requests to endpoints like /api/control/status and /api/control/installations/plan.

Sources: packages/onebots/src/control/tui-command.spec.ts:8-15, packages/onebots/src/control/tui-command.spec.ts:83-95

Installation Wizard Flow

When a user runs onebots setup, the CLI executes a specific installation sequence:

1. Status Check: Verifies if the management service is reachable via /api/control/status.
2. Catalog Fetch: Retrieves available adapters and protocols via /api/control/installations/catalog.
3. Plan Generation: Creates an installation plan via /api/control/installations/plan.
4. Activation: Applies the selected candidates to create an immutable runtime generation.

Sources: packages/onebots/src/control/tui-command.spec.ts:83-100, README.en.md:106-115

Observability and Health

The Control Service exposes several observability endpoints to monitor the gateway's state. These endpoints provide data in JSON format for the CLI/Web UI and in Prometheus format for external monitoring systems.

Sources: packages/core/src/app-observability.ts:241-260

Observability Endpoints

• /health: Returns basic process information including instance_id, uptime, and started_at.
• /ready: Provides a detailed ReadinessSnapshot indicating if the server, adapters, and protocols are operational.
• /metrics: Exports Prometheus-compatible metrics for memory usage, connection counts, and adapter status.

Sources: packages/core/src/app-observability.ts:241-285

Readiness States

The system evaluates readiness based on the following conditions:

• The application isStarted must be true.
• No active isReloading operations (e.g., configuration_reload) must be in progress.
• Disk configuration must be in_sync with the active runtime.
• All accounts and protocols must have a ready or online lifecycle status.

Sources: packages/core/src/app-observability.ts:114-150

Conclusion

The CLI and Control Service form the management backbone of OneBots. By utilizing a central ControlClient and a structured installation plan system, the project ensures consistent management across TUI, CLI, and Web interfaces while maintaining high observability through standard health and metrics endpoints.

Sources: AGENTS.md:12-25, packages/onebots/src/cli.test.ts:24-35