Command Line Interface

Command Line Interface

Bedrock Voice Chat's server executable doubles as a command line interface (CLI) that allows for remote management of Bedrock Voice Chat servers.

The CLI was made available in Beta.11

Global

These apply to every subcommand.

Flag	Env var	Default	Notes
-c, --config-file <path>	—	config.hcl	Required only by server and admin *
--server-url <url>	BVC_SERVER	https://127.0.0.1:3000	Target server for login. Other client commands read the URL from the stored identity.
--identity <gamertag:game>	BVC_IDENTITY	—	Picks which stored identity to act as when more than one is on disk.

BVC_GAMERTAG is also honored, but only by login (see below).

Identity management

Command	Flags	Auth	Transport	Description
login	-p, --gamertag <name> (env: BVC_GAMERTAG); --code <code> (prompted on stdin if omitted); -g, --game <minecraft> (default minecraft)	none	POST /api/auth/code (ncryptf)	Redeems a one-time code for an mTLS cert bundle and persists it as a CLI identity.
logout	(none)	mTLS	local	Deletes the active stored identity.
whoami	(none)	mTLS	GET /api/auth/introspect	Prints the active identity, server URL, cert expiry, and effective permissions.

Server lifecycle

Command	Flags	Auth	Transport	Description
server	(consult --config-file)	—	—	Starts the BVC server (HTTP + QUIC).

Bootstrap (server-host only, DB-direct)

These talk to the database directly. Run them on the same host as the server, with access to config.hcl.

Command	Flags	Description
admin bootstrap	-p, --player <name>; -g, --game <minecraft>	Grants admin to an existing player. Player must already exist (e.g. created by admin generate-code or auto-registered from a position event).
admin generate-code	-p, --player <name>; -g, --game <minecraft>; -d, --duration <secs> (default 3600, max 86400)	Generates a one-time login code. Creates the player record (with cert, keypair, signature) if it does not exist. Use this for the very first operator.

User management (HTTP, mTLS)

All of these require an active admin identity (whoami should show admin in its permissions).

Command	Flags	Endpoint	Description
user add	-p, --player <name>; -g, --game <minecraft>	POST /api/admin/user	Creates a player record with cert/keypair. 409 if the player already exists.
user banish	-p, --player <name>; -g, --game <minecraft>; -b, --banish <true|false> (default true)	PATCH /api/admin/user/banish	Toggles the banished flag. --banish false reverses it.
user generate-code	-p, --player <name>; -g, --game <minecraft>; -d, --duration <secs> (default 3600, max 86400)	POST /api/admin/user/code	Generates a one-time login code for an existing player. Returns 404 if the player does not exist — use user add or admin generate-code first.

Permission management (HTTP, mTLS)

Requires an active admin identity. Valid permission strings: audio_upload, audio_delete, admin, peer_link.

Permission	Grants
audio_upload	Upload audio clips to the server's audio library.
audio_delete	Delete audio clips from the library.
admin	Full administrative access — user and permission management.
peer_link	Establish cross-server peer links. Early access.

Command	Flags	Endpoint	Description
permission allow	-p, --player <name>; -g, --game <minecraft>; --permission <name>	PUT /api/admin/permission	Records an explicit allow override.
permission deny	-p, --player <name>; -g, --game <minecraft>; --permission <name>	PUT /api/admin/permission	Records an explicit deny override.
permission clear	-p, --player <name>; -g, --game <minecraft>; --permission <name>	DELETE /api/admin/permission	Removes the override; the permission falls back to the server's configured default.
permission list	-p, --player <name>; -g, --game <minecraft>	GET /api/admin/permission/{game}	Lists explicit overrides on a player. Empty output means the player is governed entirely by config defaults.

Bootstrapping a fresh deployment

# Server host, with config.hcl available:
bvc admin generate-code -p Alice -g minecraft -d 3600
# -> Code: ABCD1234

# Anywhere with network access to the server:
bvc login --gamertag Alice --code ABCD1234

# Server host:
bvc admin bootstrap -p Alice -g minecraft

# Now Alice's stored identity has admin perms
bvc whoami
bvc user add -p Bob -g minecraft
bvc user generate-code -p Bob -g minecraft