RustNotMC/docs/horizon-ctl-commands.md

<!-- Generated by `horizon-ctl help --markdown` from the command table in crates/horizon-client/src/bin/horizon-ctl/commands.rs: edit the table, then regenerate. -->
# horizon-ctl commands

Every command `horizon-ctl` takes, its MCP tool in `horizon-ctl mcp` (the launcher's `horizon-launcher mcp` offers the same tools as `game_<tool>`, all but `launch`) and its arguments. Positional arguments come first, in order; `--flags` after them. `horizon-ctl help --game` lists the game's own commands, test hooks included. Design rules and the full inventory: [agent-control.md](agent-control.md).

## Session

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `launch [--world NAME] [--seed N] [--creative] [--version TAG] [--game PATH] [--wait] [GAME ARGS...]` | `launch` | Start Horizon with the control socket and wait until it answers | `--world` (string): world folder to open or create<br>`--seed` (string): seed for a new world<br>`--creative` (boolean): creative mode for a new world<br>`--version` (string): an installed launcher version tag such as v2026.10.13<br>`--game` (string): path to a horizon-client binary<br>`--wait` (boolean): also wait until the world is ready (default in MCP)<br>`--offscreen` (boolean): render without showing a window (screenshots still work): locked or headless sessions |
| `wait-for screen NAME\|widget ID\|loaded\|chat TEXT\|event KIND [--timeout S] [--since SEQ]` | `wait_for` | Wait until the game reaches a state, then reply | `--timeout` (number): seconds (default 30)<br>`--since` (integer): chat and event: count from this event seq<br>`condition` (screen, widget, loaded, chat, event, required): what to wait for<br>`value` (text): the screen name, widget id, chat text or event kind |
| `wait-ready [SECONDS]` | `wait_ready` | Wait until the player has spawned and no chunks are pending | `seconds` (number): how long to wait (default 120) |
| `logs [--lines N] [--crash]` | `logs` | The end of the game's log, or its newest crash report | `--lines` (integer): how many lines of latest.log (default 100)<br>`--crash` (boolean): the newest crash report instead |
| `status` | `status` | Game, renderer and streaming state (the scripting socket's original summary) | none |
| `worlds` | `worlds` | The saved worlds, newest first: folder, name, mode, last played, version | none |
| `world-rename FOLDER NAME` | `world_rename` | Rename a world, as Edit World does (its folder stays) | `folder` (string, required): world folder from worlds<br>`name` (text, required): the new name |
| `world-backup FOLDER` | `world_backup` | Zip a world into backups/, as Edit World's Make Backup does | `folder` (string, required): world folder from worlds |
| `world-delete FOLDER --confirm` | `world_delete` (destructive) | Delete a world for good, as Select World's Delete does | `folder` (string, required): world folder from worlds<br>`--confirm` (boolean, required): true once the player agreed: it cannot be undone |
| `open WORLD [SEED] [creative]` | `open` | Open or create a world from the title screen | `world` (string, required): world folder<br>`seed` (integer): seed for a new world<br>`mode` (creative): creative for a creative world |
| `save` | `save` | Save the world | none |
| `quit` | `quit` | Save and exit the game | none |
| `screenshot PATH` | `screenshot` | Write the next rendered frame as a PNG | none |

## Observe (JSON state)

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `events [--since SEQ]` | `events` | What happened since SEQ, oldest first: screens, chat, deaths, respawns, items gained or lost, dimensions, worlds | `--since` (integer): only events after this seq |
| `state` | `state` | Player, world, screen and crosshair target in one reply | none |
| `looking-at` | `looking_at` | The block or entity under the crosshair | none |
| `entities [RADIUS] [TYPE]` | `entities` | Mobs, dropped items and experience orbs near the player, nearest first | `radius` (number): search radius in blocks (default 32)<br>`type` (string): entity type filter |
| `block X Y Z` | `block` | The block state at a position | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z |
| `light X1 Y1 Z1 X2 Y2 Z2` | `light` | The stored sky and block light of a box | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z |
| `blocks X1 Y1 Z1 X2 Y2 Z2` | `blocks` | The non-air blocks of a box, with counts per block | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z |
| `find-block BLOCK [RADIUS]` | `find_block` | The nearest loaded blocks of a kind | `block` (string, required): block id such as oak_log<br>`radius` (integer): search radius (default 32) |
| `inventory` | `inventory` | Hotbar, main inventory, armor, offhand, carried stack and item counts | none |
| `screen` | `screen` | The open screen or title menu, its buttons and its slots | none |
| `messages [N]` | `messages` | Recent chat and system messages, the title and the action bar | `n` (integer): how many chat lines (default 20) |
| `menu` | CLI only | The open menu's slots and carried stack, with station details | none |

## Move and look

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `move forward\|back\|left\|right SECONDS [--sprint] [--sneak] [--jump]` | `move` | Walk in a direction relative to the view for a time | `direction` (forward, back, left, right, required): direction relative to the view<br>`seconds` (number, required): how long to walk<br>`--sprint` (boolean): sprint<br>`--sneak` (boolean): sneak<br>`--jump` (boolean): keep jumping |
| `goto X Y Z [--near R] [--sprint] [--direct] [--timeout S]` | `goto` | Walk to a position, finding a path through loaded terrain | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate<br>`--near` (number): arrive within this many blocks (default 0.6)<br>`--sprint` (boolean): sprint<br>`--direct` (boolean): walk straight when no path is found<br>`--timeout` (number): give up after this many seconds (default 60) |
| `jump` | `jump` | Jump once and reply when landed | none |
| `look YAW PITCH` | `look` | Set the view direction in degrees | `yaw` (number, required): yaw in degrees<br>`pitch` (number, required): pitch in degrees (-90 up .. 90 down) |
| `turn DYAW DPITCH [--over S]` | `turn` | Rotate the view by an amount | `dyaw` (number, required): yaw change in degrees<br>`dpitch` (number, required): pitch change in degrees<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `mouse-move DX DY` | `mouse_move` | Move the mouse: relative motion that turns the view like a player's mouse | `dx` (number, required): horizontal motion (positive turns right)<br>`dy` (number, required): vertical motion (positive looks down) |
| `look-at X Y Z \| look-at block X Y Z [FACE] \| look-at entity ID  [--over S]` | `look_at` | Turn to face a point, a block (a visible face of it) or an entity | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `look-at-block X Y Z [FACE] [--over S]` | `look_at_block` | Aim the crosshair at a block (same as look-at block) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`face` (down, up, north, south, west, east): which face to aim at<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `look-at-entity ID [--over S]` | `look_at_entity` | Face an entity (same as look-at entity) | `id` (integer, required): entity id from entities<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `tp X Y Z` | `tp` | Teleport the player | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate |

## Act on the world

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `break X Y Z [--timeout S]` | `break` | Mine a block, holding the attack button until it breaks | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`--timeout` (number): give up after this many seconds (default 30) |
| `place X Y Z [--item ITEM]` | `place` | Place the held item (or ITEM from the hotbar) at an empty position | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`--item` (string): hotbar item to select first |
| `interact X Y Z [FACE]` | `interact` | Right-click a block: open a chest or crafting table, press a button, open a door | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`face` (down, up, north, south, west, east): which face to click |
| `use-item [--hold SECONDS]` | `use_item` | Right-click with the held item: eat, drink, throw, draw a bow | `--hold` (number): hold the button this long |
| `attack [ID]` | `attack` | Swing at what the crosshair targets (after facing entity ID) | `id` (integer): entity id to face first |
| `select SLOT\|ITEM` | `select` | Select a hotbar slot 1-9, or the hotbar slot holding ITEM | `slot` (string, required): 1-9 or an item id |
| `drop [all]` | `drop` | Drop one of the held item, or the whole stack | `all` (boolean): drop the whole stack |
| `hold KEY SECONDS` | CLI only | Press a key, wait, release it | `key` (string, required): key name<br>`seconds` (number, required): how long |
| `key KEY down\|up\|tap\|repeat` | `key` | Press, release or auto-repeat a key (w a s d space shift ctrl e q esc f3 1-9 arrows ...) | `key` (string, required): key name<br>`action` (down, up, tap, repeat, required): what to do |
| `mouse left\|right\|middle down\|up\|click` | `mouse` | Press or release a mouse button in the world | `button` (left, right, middle, required): button<br>`action` (down, up, click, required): what to do |
| `interact-entity ID` | `interact_entity` | Right-click an entity: trade with a villager, mount a horse, ride a boat, shear a sheep | `id` (integer, required): entity id from entities |
| `pad BUTTON down\|up\|tap \| pad stick left\|right X Y \| pad trigger left\|right V \| pad release \| pad status` | `pad` | A virtual controller: buttons, sticks and triggers as a real pad would send them | `what` (string, required): a button name, stick, trigger, release or status<br>`a` (string): down\|up\|tap, or left\|right<br>`b` (number): stick X or trigger value<br>`c` (number): stick Y |
| `release` | `release` | Release every key and mouse button | none |
| `stop` | `stop` | Cancel the running action (goto, break...) and release every key | none |

## Screens, menus and chat

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `open-inventory` | `open_inventory` | Open the inventory screen (crafting grid 100-103, result 200) | none |
| `click-slot SLOT [right] [shift]` | `click_slot` | Click a slot of the open inventory or menu | `slot` (integer, required): slot id<br>`right` (boolean): right-click<br>`shift` (boolean): shift-click |
| `close` | `close` | Close the open menu and return to the game | none |
| `ui` | `ui` | Every widget of the open screen: id, kind, label, bounds, value | none |
| `click ID [right\|middle] [shift]` | `click` | Click a widget of ui by its id, as the mouse would | `id` (string, required): widget id from ui<br>`right` (boolean): right-click<br>`middle` (boolean): middle-click<br>`shift` (boolean): shift-click (slots) |
| `set ID VALUE` | `set` | Move a slider of ui to VALUE (0..1), as a click on its track | `id` (string, required): slider id from ui<br>`value` (number, required): 0..1 along the track |
| `options-get [KEY...]` | `options_get` | The game's options (options.txt) by key, with their type and range or choices | `keys` (text): option keys (default: all) |
| `options-set KEY VALUE` | `options_set` | Set one option, apply it at once and save options.txt, as the options screen does | `key` (string, required): option key from options-get<br>`value` (text, required): the new value |
| `click-button LABEL` | `click_button` | Click a button of the open screen or title menu by its label | `label` (text, required): button label |
| `click-at X Y [right]` | `click_at` | Click at GUI pixel X Y of the window (screen gives button rectangles) | `x` (number, required): GUI x<br>`y` (number, required): GUI y<br>`right` (boolean): right-click |
| `drag-at [right] X Y X Y...` | `drag_at` | Press at the first GUI point, move through the others, release at the last | `points` (text, required): right, then GUI x y pairs |
| `scroll-at X Y STEPS` | `scroll_at` | Turn the mouse wheel at GUI pixel X Y (positive scrolls up) | `x` (number, required): GUI x<br>`y` (number, required): GUI y<br>`steps` (number, required): wheel steps |
| `type [--field name\|seed] [--replace] TEXT` | `type` | Type into the focused text field (chat box, world name, anvil, sign...) | `--field` (name, seed): create-world field to type into<br>`--replace` (boolean): clear the field first<br>`text` (text, required): text to type |
| `chat TEXT` | `chat` (network) | Send a chat line (or a /command) as if typed | `text` (text, required): message |
| `command TEXT` | `command` (network) | Run a command (the leading / is optional) | `command` (text, required): command line |
| `respawn` | `respawn` | Respawn from the death screen | none |
| `pause` | `pause` | Open the pause menu | none |
| `resume` | `resume` | Leave the pause menu | none |
| `options [PAGE]` | `options` | Open the options screen, or one of its pages (Horizon's too) | `page` (main, video, sound, controls, keybinds, controller, controller-binds, mouse, chat, accessibility, language, font, packs, mods, shader-packs, graphics, graphics-advanced, extras, horizon, agent): the page (default: the main options) |
| `book [next\|back\|take\|done]` | `book` | The open book or lectern: its page text, or press one of its buttons | `action` (next, back, take, done): a button to press |
| `signedit X Y Z [front\|back]` | `signedit` | Open the sign editor of the sign at X Y Z (then type and close) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`side` (front, back): which side |
| `mount-menu` | `mount_menu` | Open the inventory of the horse, donkey, mule or llama being ridden | none |
| `chat-log [N]` | CLI only | The newest N chat messages | none |

## Multiplayer, LAN and friends

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `connect ADDRESS [NAME]` | `connect` (network) | Join a multiplayer server, or a friend's world by its invite code, from the title screen | `address` (string, required): HOST[:PORT] or friend:CODE<br>`name` (string): player name when offline |
| `disconnect` | `disconnect` | Leave the server, back to the server list | none |
| `servers` | `servers` | The Multiplayer screen's server list: name and address | none |
| `lan open [PORT] [commands] [force] \| lan close \| lan status` | `lan` (network) | Open the world to LAN (Open to LAN), stop, or see the guests | `action` (open, close, status, required): what to do<br>`port` (integer): port for open<br>`commands` (boolean): allow cheats<br>`force` (boolean): force the game mode |
| `friends host\|stop\|status` | `friends` (network) | Play with Friends: share the open world behind an invite code, stop, or see who joined | `action` (host, stop, status, required): what to do |

## World and cheats

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `give ITEM [COUNT]` | `give` | Add items to the inventory | `item` (string, required): item id<br>`count` (integer): how many (default 1) |
| `time TICKS` | `time` | Set the time of day (0 sunrise, 6000 noon, 13000 night) | `ticks` (integer, required): day time |
| `setblock X Y Z BLOCK[props]` | `setblock` (destructive) | Set a block (with neighbour updates) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`block` (string, required): block state such as oak_stairs[facing=east] |
| `summon KIND [X Y Z] [baby]` | `summon` | Spawn a mob (in front of the player without a position) | `kind` (string, required): mob type<br>`x` (number): X<br>`y` (number): Y<br>`z` (number): Z<br>`baby` (boolean): a baby |
| `effect ID SECONDS [AMPLIFIER] \| effect clear` | `effect` | Give a status effect, or clear them all | `id` (string, required): effect id such as speed, or clear<br>`seconds` (number): duration<br>`amplifier` (integer): level - 1 (default 0) |
| `effects` | `effects` | The player's active status effects | none |
| `xp LEVELS` | `xp` | Add experience levels (negative removes) | `levels` (integer, required): levels to add |
| `enchant ID LEVEL` | `enchant` | Enchant the held item (a book stores it) | `id` (string, required): enchantment id<br>`level` (integer, required): level |
| `potion ITEM POTION` | `potion` | Give a potion item | `item` (potion, splash_potion, lingering_potion, tipped_arrow, required): which item<br>`potion` (string, required): potion id |
| `fill X1 Y1 Z1 X2 Y2 Z2 BLOCK` | `fill` (destructive) | Set a box of loaded blocks | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z<br>`block` (string, required): block state |
| `container X Y Z [ITEM COUNT]` | `container` | List a container's items, or add items to it | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`item` (string): item to add<br>`count` (integer): how many |
| `render-distance N` | CLI only | Chunks, 2..64 | `chunks` (integer, required): render distance |
| `wait TICKS` | `wait` | Wait until TICKS game ticks have passed (20 per second) | `ticks` (integer, required): game ticks |

## Scripting and benchmarks

| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `script [FILE] [--keep-going]` | CLI only | Run commands from FILE (or stdin), one per line | none |
| `sleep SECONDS` | CLI only | Wait (in scripts) | none |
| `mcp` | CLI only | Serve the Model Context Protocol on stdin/stdout, one tool per command | none |
| `bench SECONDS` | `bench` | Reset frame stats, wait, reply with the summary | `seconds` (number, required): how long to measure |
| `stats [reset]` | `stats` | Frame-time summary since the last reset | `reset` (boolean): start counting again |
| `fly X1 Y1 Z1 X2 Y2 Z2 SECONDS [PITCH [raw]]` | CLI only | Fly the camera along a line, then reply with the frame summary | none |