bsm-cli

Introduction

bsm-cli is a command-line interface tool for managing Minecraft Bedrock Dedicated Servers via the Bedrock Server Manager API.

Features

• Full CLI interface using click and questionary.
• Interactive menus for server management.
• Realtime server state updates via WebSocket.
• Seamlessly manages configuration for server and backups.

Installation

Install the library using pip:

pip install bsm-cli

Quick Start

You can invoke the CLI using:

bsm-cli

Which will trigger the interactive menu allowing you to manage and configure your Bedrock Dedicated Servers.

OpenAPI commands

The CLI targets BSM's typed-contract branch and stable operation IDs. Curated commands remain available; new server/plugin HTTP endpoints can be inspected and called immediately:

bsm-cli api info
bsm-cli api schema
bsm-cli api operations --tag 'Server Management'
bsm-cli api operation start_server
bsm-cli api call start_server --param server_name=survival
bsm-cli api diff --against-generated
bsm-cli api diff --against saved-openapi.json
bsm-cli api refresh
bsm-cli api export saved-openapi.json
bsm-cli plugin operations discord
bsm-cli plugin call discord discord_status

--param NAME=VALUE uses declared path/query/header parameter types. Boolean values use true/false; arrays and objects use JSON. Missing, duplicate, and unknown parameters fail before invoking an endpoint. Cookie parameters are not currently supported by the generic CLI. Query arrays and objects honor form explode, deepObject, spaceDelimited and pipeDelimited serialization.

Request-body options:

bsm-cli api call send_command --param server_name=survival --json '{"command":"list"}'
bsm-cli api call login --form username=admin --form password=example
bsm-cli api call plugin_upload --file file=./addon.mcaddon

The global --json flag precedes the command; the call-specific --json option is a request body and follows the operation:

bsm-cli --json api call send_command --param server_name=survival --json '{"command":"list"}'
bsm-cli --json server list

JSON output contains structured API responses, without human progress/table text. Commands making multiple calls return an ordered array of responses unless they provide their own result. Errors are JSON objects on stderr. Resource monitoring returns one snapshot in JSON mode; server list --loop requires human output. Interactive commands may still prompt; supply their options for scripting.

Human discovery output uses tables. Interactive menus browse Click's registered command groups and add a Plugin API menu only when the live schema has plugin operations. api refresh caches operation/plugin/parameter completion; on servers advertising list_servers, it also caches server-name completion. Completion does not make network requests and ignores caches belonging to another configured URL.

Enable Click shell completion, for example in Bash:

eval "$(_BSM_CLI_COMPLETE=bash_source bsm-cli)"

For Python client examples and OpenAPI discovery, see the API usage guide.

Content and task behavior

world install --file, addon install --file, and backup restore --file select files already present on the backend. They do not upload a local file. Examples:

bsm-cli world install --server survival --file MyWorld.mcworld --yes
bsm-cli addon install --server survival --file Example.mcaddon
bsm-cli backup restore --server survival --file MyWorld_backup_20261007_120000.mcworld
bsm-cli backup restore --server survival --file custom-backup.zip --type world

content upload LOCAL_FILE works only when the server advertises an upload_content operation. The current backend does not advertise one. Place content files in the backend's content directories, then select them by name.

Background commands subscribe to the task's WebSocket topic and check its REST snapshot after subscribing, covering tasks that finish before monitoring starts. A silent or disconnected WebSocket falls back to REST polling. Failed and cancelled tasks exit with a nonzero status.

Registry menus accept a single value or a JSON array for repeated options and variadic arguments, preserving spaces in player names and paths. Password inputs are hidden and password confirmations are checked.

Contract review and streaming downloads

bsm-cli api operations --method GET --plugin example
bsm-cli --json api diff --against saved-openapi.json --details
bsm-cli api download example_download ./archive.zip --param name=example

api download streams a discovered GET operation and replaces the destination only after a complete download. JSON mode returns the output path and byte count. api diff --details includes conservative compatibility classifications alongside the usual added/removed/changed lists. Invalid saved schemas produce input errors.

Completion validates cached contracts and fingerprints and rejects metadata for a different backend URL or recorded user. Malformed caches yield no suggestions. Boolean and enum parameter values have completion suggestions. Interactive command menus can select live operation IDs and return to the menu after each action.

Manager dashboard and settings

The home menu opens Overview, Monitor, and Operations directly. Select a server to see its lifecycle, configuration, backup, and world actions on one screen. Menus with a list display it automatically before offering actions. Operations can be selected directly to inspect their outcomes.

These views are also available without entering the menu:

bsm-cli auth setup --base-url http://localhost:11325
bsm-cli overview
bsm-cli health
bsm-cli monitor
bsm-cli monitor --once --unit GB
bsm-cli operations list
bsm-cli operations show TASK_ID
bsm-cli audit
bsm-cli logs --topic app_logs

Application commands use their direct paths (overview, monitor, settings, health, logs, audit, and operations). Server monitoring and settings live under server; the duplicate manager and system groups have been removed. Use bsm-cli server monitor --server survival for a single server.

Overview, monitoring, and operation lists use structured terminal tables. In an interactive menu, Ctrl+C stops the active live view and returns to its menu; standalone live commands still exit normally on Ctrl+C.

Live views reconnect automatically and reconcile WebSocket updates with HTTP snapshots. Revision checks prevent older snapshots from replacing newer state. Application monitoring separates app and system metrics and shows recent CPU history. Log history returns a cursor for requesting older pages.

bsm-cli settings
bsm-cli server settings --server survival
bsm-cli plugin settings edit backup_on_start
bsm-cli plugin settings show backup_on_start
bsm-cli plugin settings set backup_on_start settings.json
bsm-cli appearance set --memory-unit GB --density compact

The shared settings editor reviews changes before saving. Plugin schemas provide field descriptions, bounds, enums, and server checklists; plugins without settings have no Settings action. Credential fields are masked. Application and server settings infer field types from their current values because those endpoints do not advertise an editable settings schema. Backend validation remains authoritative.

An editor refuses to save if its settings changed in another session. Global and server settings are saved one key at a time; the CLI prints each successfully saved key so partial updates remain visible if a later request fails. Plugins use one request to replace their settings. --json continues to return structured API data for noninteractive commands; use plugin settings set for scripted updates.

Use bsm-cli auth login --remember-me to request the backend-configured longer token lifetime. Interactive login also offers this choice, defaulting to off. The CLI saves the issued token without storing your password; the flag cannot extend the lifetime of an existing token supplied with --token.

Administrative diagnostics

bsm-cli diagnostics snapshot
bsm-cli diagnostics snapshot --subsystem runtime
bsm-cli diagnostics history --outcome failed --limit 50
bsm-cli diagnostics history --cursor RETURNED_CURSOR
bsm-cli diagnostics runs
bsm-cli diagnostics trace CORRELATION_ID
bsm-cli --json diagnostics snapshot > before.json
bsm-cli --json diagnostics snapshot > after.json
bsm-cli diagnostics compare before.json after.json

History supports subsystem, instance, owner, code, outcome, operation and correlation filters. Trace sources may be independently unavailable. Comparison accepts snapshots or the snapshot member of saved support reports; counter deltas are unavailable across instance changes. All commands support the existing --json output and administrator error policy. Requests are on demand; no new background polling is added.

Support reports

On a backend with diagnostic endpoints, an administrator can save a sanitized report:

bsm-cli diagnostics report --output bsm-support-report.json

The command discovers the live get_diagnostic_report operation and uses your configured authentication. The destination is published only after the response completes. Use --force to replace an existing file. Reports contain subsystem metadata and bounded history; inspect them before sharing. Older backends report that the operation is unavailable.