Command Reference
The full surface: 110 commands in 17 groups, exactly as returned by api.describe. This page is the map; full parameter schemas, response shapes and error cases for every command live in docs/API.md.
Conventions:
- (op): returns
{"op": N}; poll ops.status, block with ops.wait, or watch op.* events. See Concepts.
- (local-only): refused over TCP/WebSocket regardless of token scope; works only on the trusted local socket / named pipe.
- Commands that target an instance accept
id (ephemeral slab address "index:generation") or name (stable, case-insensitive).
launcher (9)
| Command |
Description |
launcher.version |
Version, protocol and session_id |
launcher.status |
Uptime, instance counts, current_seq |
launcher.focus |
Open/focus the main window |
launcher.quit |
Ask the launcher to quit (local-only) |
launcher.install_update |
Apply the cached self-update (op, local-only) |
launcher.plan |
Dry-run a desired-state document, returns replayable actions |
status.summary |
Plain-language overall status |
health.check |
Composed health probe (backend loop + disk) |
game.capture |
Opt into game-output capture regardless of the GUI setting |
instances (30)
| Command |
Description |
instances.list |
All instances |
instances.get |
One instance by id or name |
instances.create |
Create an instance (name/version/loader only) |
instances.ensure |
Idempotent create-if-absent + apply configuration |
instances.clone |
Duplicate an instance |
instances.delete |
Delete an instance |
instances.rename |
Rename |
instances.relocate |
Move the instance folder |
instances.create_shortcut |
Desktop shortcut |
instances.start |
Launch (wait: running|exited to block) (op) |
instances.kill |
Kill the running game |
instances.set |
Set configuration fields (two-phase validation, atomic) |
instances.export |
Export to zip/modrinth/curseforge (op) |
instances.import_file |
Create from a .mrpack (op) |
instances.update_check |
Check content updates (op) |
instances.worlds |
List worlds |
instances.servers |
List servers |
instances.content |
List content in a folder (mods/resourcepacks/shaders) |
instances.logs |
List log files |
instances.diff |
Diff two instances' content |
instances.manifest |
Full declarative manifest + effective JVM flags |
instances.sessions |
Playtime + current-session state |
instances.screenshots |
List screenshots (optional base64 thumbnails) |
instances.crash_reports |
List/read crash reports + hs_err logs |
instances.snapshot |
Snapshot mods/config to snapshots/<inst>/<tag> (op) |
instances.restore |
Restore a snapshot (op) |
instances.snapshots |
List snapshots |
servers.reorder |
Reorder the instance's servers.dat |
servers.set |
Replace the instance server list |
servers.status |
Ping server(s) for MOTD/players/latency (local-only) |
content (13)
| Command |
Description |
content.search |
Search Modrinth/CurseForge |
content.versions |
List versions/files for a project |
content.install |
Install content from Modrinth/CurseForge/local file (op) |
content.sync |
Reconcile mods to a desired set, by provenance |
content.set_enabled |
Enable/disable content |
content.delete |
Delete content |
content.update |
Update one content item (op) |
content.set_child_enabled |
Toggle a modpack child |
content.download_children |
Download modpack children (op) |
content.resolve |
Resolve entries to concrete version + sha1 (dry run) |
content.dev_link |
Symlink dev jars into an instance by glob |
content.bisect_start |
Begin a mod bisection to find a culprit |
content.bisect_step |
Report reproduced|gone, advance the bisection |
accounts (11)
| Command |
Description |
accounts.list |
List accounts + selected |
accounts.add_offline |
Add an offline account (vanilla OfflinePlayer: UUID derivation) |
accounts.login |
Microsoft login (op, visit_url) |
accounts.reauth |
Re-auth an existing account (op) |
accounts.select |
Select the active account |
accounts.delete |
Delete an account |
accounts.reorder |
Reorder accounts |
accounts.skin_get |
Get the active skin |
accounts.skin_set |
Set the skin (base64 PNG) |
accounts.capes_get |
List capes |
accounts.cape_set |
Set/clear the active cape |
skins (4)
| Command |
Description |
skins.library |
List library skins |
skins.add |
Add a skin from URL or file |
skins.remove |
Remove a library skin |
skins.copy_player |
Copy another player's skin |
sync_settings (5)
| Command |
Description |
sync.state |
Sync targets state |
sync.set |
Toggle a sync target |
settings.get |
Backend settings (proxy password redacted) |
settings.set_open_game_output |
Toggle the game-output window |
settings.set_proxy |
Set the launcher proxy (restart to apply) |
logs (4)
| Command |
Description |
logs.read |
Read a log file (gzip-aware) |
logs.tail |
Tail a log (bounded), filter by level/pattern |
logs.upload |
Upload a log to mclo.gs (op) |
logs.cleanup |
Delete rotated log files |
diagnostics_iac (2)
| Command |
Description |
diagnostics.analyze |
Heuristic log/crash analysis (likely causes + suggestions) |
state.export |
Export the whole launcher as a revisioned declarative document |
worlds (4)
| Command |
Description |
worlds.backup |
Zip a world into .minecraft/backups/ |
worlds.restore |
Restore a world from a backup zip (atomic: extract-then-swap) |
worlds.duplicate |
Copy a world to a new name |
worlds.delete |
Delete a world |
hooks (3)
| Command |
Description |
hooks.register |
Register an outbound webhook, optional HMAC-SHA256 secret (local-only) |
hooks.list |
List webhooks (secret hidden) |
hooks.delete |
Delete a webhook by id (local-only) |
network (8)
| Command |
Description |
auth.hello |
Handshake: nonce + auth_required (pre-auth) |
auth.bearer |
Authenticate with a token secret (pre-auth) |
auth.prove |
Authenticate via HMAC challenge over the nonce (pre-auth) |
auth.whoami |
Current connection identity + scopes |
auth.mint_token |
Mint a scoped token (local-only) |
auth.list_tokens |
List tokens, secrets hidden (local-only) |
auth.revoke_token |
Revoke a token by id (local-only) |
net.status |
Network transport status (bind, tokens, allowlist) |
import (2)
| Command |
Description |
import.scan |
Scan another launcher (Prism/CurseForge/Modrinth/MultiMC/ATLauncher) for importable instances |
import.run |
Import from another launcher (op) |
metadata (2)
| Command |
Description |
metadata.minecraft_versions |
Cached Mojang version manifest |
metadata.download_all |
Prefetch all metadata (heavy: 1000+ fetches, no op handle) |
bookmarks (3)
| Command |
Description |
bookmarks.add |
Add a named shortcut (instance + optional server/world) |
bookmarks.list |
List bookmarks |
bookmarks.remove |
Remove a bookmark |
operations (4)
| Command |
Description |
ops.list |
List tracked ops (running + finished for up to an hour) |
ops.status |
One op's status |
ops.wait |
Block until an op finishes |
ops.cancel |
Request cooperative cancellation |
events (2)
| Command |
Description |
events.subscribe |
Stream events; params {types, instance, since_seq} |
api.describe |
This command registry, the event list, and the security block |
observability (4)
| Command |
Description |
backend.ping |
Message-loop liveness roundtrip |
metrics.instances |
Per-instance RSS/CPU/session uptime |
metrics.storage |
Bytes per instance + caches (full directory walk) |
metrics.prometheus |
OpenMetrics text exposition, ready to scrape |
Events (19)
Every event line carries a monotonic seq; see Concepts for replay, filters and lag semantics.
Launcher and account state (mirrored from the UI):
| Event |
Fires |
instance.added |
An instance appeared (created, imported, or a folder dropped into instances/) |
instance.removed |
An instance was deleted |
instance.modified |
Status transitions and configuration changes (the only carrier of status) |
instance.playtime |
Every second while a game session is running |
accounts.updated |
Full account list on any account change |
notification |
The launcher's toast messages (success/info/warning/error) |
launcher.update_available |
A self-update was offered (feeds launcher.install_update) |
Op lifecycle (follow long-running work without polling):
| Event |
Fires |
op.started |
An op was registered |
op.progress |
An op's tracker set or aggregate count changed (detail = the ops.status object) |
op.finished |
Exactly once when an op completes, successfully or with an error |
Live game events (require game-output capture: the GUI setting or game.capture; decided at launch time). The semantic events are best-effort parses of the game log, vanilla-oriented and version-dependent; treat them as hints layered on game.output:
| Event |
Fires |
game.output |
Batched console stdout/stderr lines, tagged by instance, with parsed level |
game.ready |
The game reaches a near-playable state |
game.world_loading |
An integrated server starts (single-player load) |
game.server_connected |
The client connects to a multiplayer server (host, port) |
game.player_chat |
A [CHAT] line is logged (message) |
game.stopping |
The game logs its shutdown |
game.crash |
A fatal line or crash-report marker is seen (line) |
game.exited |
All of an instance's game processes have fully exited |
Flow control:
| Event |
Fires |
events.lagged |
The consumer read too slowly and lost events (missed); re-subscribe with since_seq |