The mp CLI and npm Configuration

Why a CLI exists

Three real workflows justify it: smoke-testing a deployment (mp time, mp bench), one-off admin actions without writing a script (ban a player, update game data), and debugging integrations by replaying the exact calls your game makes. It is deliberately thin — a switch over the SDK's public methods — so the CLI can never drift from SDK behavior.

Credentials via environment, never argv

Tokens are read only from environment variables — command-line arguments are visible in process lists and shell history, so the CLI refuses to take credentials that way.

export MP_API_TOKEN="your-api-token"          # required
export MP_PLAYER_TOKEN="player-credential"    # for player-scoped commands
export MP_PRIVATE_TOKEN="admin-credential"    # for admin commands only
export MP_BASE_URL="https://api.michitai.com/api"  # optional override

Exit codes: 0 on success, 1 on usage/transport error, 2 when the API itself answered success: false — scripts can branch on all three.

Command reference

mp register PlayerOne '{"level":1}'   # prints private_key — save it
mp login | heartbeat | logout         # session lifecycle
mp data get | mp data update '{"wins":3}'

mp rooms list [search]
mp rooms create "Lobby" --max 4 --realtime
mp rooms join ROOM_ID --password pw
mp rooms players | leave | current | heartbeat
mp rooms kick PLAYER_ID | rooms stop   # host only

mp mm list | mm create "Queue" --max 4 --realtime
mp mm join ID | mm players | mm start | mm stop

mp leaderboard wins level --limit 25   # ranked by player-data fields
mp friends list | lookup TAG | accept ID
mp censor "text to check"
mp time                                # server clock
mp realtime-token                      # mint a realtime credential
mp bench 100                           # p50/p95/p99 vs time.php

mp admin players                       # needs MP_PRIVATE_TOKEN
mp admin ban PLAYER_ID "reason"
mp admin game-data update '{"season":2}'

mp bench is the tool behind the numbers on Latency & Performance — run it from your own environment to get your own percentiles.

npm install and the .npmrc file

.npmrc is npm's configuration file — an ini-format file that controls registry URLs, auth, cache behavior and install defaults. It lives at four levels: per-project (./.npmrc), per-user (~/.npmrc), global, and npm's built-in defaults; nearest wins. It configures npm — it is not a feature or config file of this API.

For this SDK the stock registry needs no .npmrc at all:

# The SDK isn't on the public registry yet — install from the SDK.zip download:
npm install ./michitai-multiplayer    # file: dependency, needs no .npmrc at all

# After publication (planned), this will be the command:
# npm install michitai-multiplayer

When you do need one — a private registry mirror, an artifact repository, or a scoped package later:

# project .npmrc — commit this (no secrets)
registry=https://registry.npmjs.org/
@michitai:registry=https://npm.pkg.example.com/
# auth tokens live in the USER ~/.npmrc, never in the repo:
# //npm.pkg.example.com/:_authToken=${NPM_TOKEN}

Rules that keep you out of trouble: never commit a line containing _authToken (env-var indirection like ${NPM_TOKEN} is the safe pattern); don't set strict-ssl=false or unknown registries to silence an install error — that disables the TLS check that proves the package is genuine; and commit package-lock.json so every environment installs the same resolved versions (npm ci in CI).