# 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_`, 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
`--seed` (string): seed for a new world
`--creative` (boolean): creative mode for a new world
`--version` (string): an installed launcher version tag such as v2026.10.13
`--game` (string): path to a horizon-client binary
`--wait` (boolean): also wait until the world is ready (default in MCP)
`--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)
`--since` (integer): chat and event: count from this event seq
`condition` (screen, widget, loaded, chat, event, required): what to wait for
`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)
`--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
`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
`--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
`seed` (integer): seed for a new world
`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)
`type` (string): entity type filter | | `block X Y Z` | `block` | The block state at a position | `x` (integer, required): block X
`y` (integer, required): block Y
`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
`y1` (integer, required): corner Y
`z1` (integer, required): corner Z
`x2` (integer, required): opposite X
`y2` (integer, required): opposite Y
`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
`y1` (integer, required): corner Y
`z1` (integer, required): corner Z
`x2` (integer, required): opposite X
`y2` (integer, required): opposite Y
`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
`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
`seconds` (number, required): how long to walk
`--sprint` (boolean): sprint
`--sneak` (boolean): sneak
`--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
`y` (number, required): Y coordinate
`z` (number, required): Z coordinate
`--near` (number): arrive within this many blocks (default 0.6)
`--sprint` (boolean): sprint
`--direct` (boolean): walk straight when no path is found
`--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
`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
`dpitch` (number, required): pitch change in degrees
`--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)
`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
`y` (number, required): Y coordinate
`z` (number, required): Z coordinate
`--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
`y` (integer, required): block Y
`z` (integer, required): block Z
`face` (down, up, north, south, west, east): which face to aim at
`--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
`--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
`y` (number, required): Y coordinate
`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
`y` (integer, required): block Y
`z` (integer, required): block Z
`--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
`y` (integer, required): block Y
`z` (integer, required): block Z
`--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
`y` (integer, required): block Y
`z` (integer, required): block Z
`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
`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
`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
`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
`a` (string): down\|up\|tap, or left\|right
`b` (number): stick X or trigger value
`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
`right` (boolean): right-click
`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
`right` (boolean): right-click
`middle` (boolean): middle-click
`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
`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
`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
`y` (number, required): GUI y
`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
`y` (number, required): GUI y
`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
`--replace` (boolean): clear the field first
`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
`y` (integer, required): block Y
`z` (integer, required): block Z
`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
`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
`port` (integer): port for open
`commands` (boolean): allow cheats
`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
`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
`y` (integer, required): block Y
`z` (integer, required): block Z
`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
`x` (number): X
`y` (number): Y
`z` (number): Z
`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
`seconds` (number): duration
`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
`level` (integer, required): level | | `potion ITEM POTION` | `potion` | Give a potion item | `item` (potion, splash_potion, lingering_potion, tipped_arrow, required): which item
`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
`y1` (integer, required): corner Y
`z1` (integer, required): corner Z
`x2` (integer, required): opposite X
`y2` (integer, required): opposite Y
`z2` (integer, required): opposite Z
`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
`y` (integer, required): block Y
`z` (integer, required): block Z
`item` (string): item to add
`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 |