horizon/docs/horizon-ctl-commands.md

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.

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 --headless (boolean): no display, window or GPU: a player that plays through these commands only (no screenshots)
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
hello	hello	The control protocol's version, the game's release and the command groups it serves	none
memory	memory	What holds the game's memory: resident set, allocator, client and server columns by part, renderer, GPU memory by resource	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
input-log [--since SEQ] [--limit N] [--origin user|agent|game]	input_log	Recent input and who caused it: a person, an agent or the game	--since (integer): only events after this seq --limit (integer): newest N events --origin (user, agent, game): user, agent or game
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
narration	narration	What the narrator was last asked to say, oldest first, and its status	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
emote [ID|stop]	emote	Play one of the player's emotes, stop it, or list them	id (string): an owned emote's id, or stop
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 connection connected|disconnected	pad	A virtual controller: buttons, sticks and triggers as a real pad would send them	what (string, required): a button name, stick, trigger, release, status or connection a (string): down|up|tap, left|right, or connected|disconnected 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, graphics-hdr, extras, horizon, agent, video-vanilla): 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..128	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] [raw]	stats	Frame-time summary since the last reset	reset (boolean): start counting again raw (boolean): every frame time too (frame_ms, cpu_ms, gpu_ms)
gpu-passes [on|off]	CLI only	Time Horizon's own render passes on the GPU, shown in F3 and in stats and bench	mode (on, off): on or off; without it, only reports
trace [FILE [SECONDS] | stop]	CLI only	Write every thread's timed spans to FILE as a timeline that ui.perfetto.dev opens, for SECONDS or until stop	none
screenshot-sequence FRAMES STEP_MS PATH|cancel	CLI only	Draw a shader pack's first FRAMES frames on a set clock and write the last as a PNG	frames (string, required): frames to draw, 1 to 10000, or cancel step_ms (number): milliseconds between frames on the pack's clock, more than 0 (16.666667 for 60 fps) path (text): the PNG to write
render-capture on|off|DIR	CLI only	Keep CPU copies of the meshes the renderer draws (on), or write the next frame's scene to DIR for the scene_replay example	none
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
record-start [NAME] [--no-world]	record_start	Record input, state and the world for a bug repro	name (string): folder name after the timestamp (default session) --no-world (boolean): do not copy the world (a server session)
record-stop [--export]	record_stop	Stop the recording (and write the repro zip)	--export (boolean): write the repro bundle too
record-status	record_status	The running recording and replay, if any	none
record-list	record_list	The recordings and repro bundles on disk	none
record-replay NAME [--stop] [--in-place] [--keep-world] [--timeout S]	record_replay	Replay a recording, best effort	name (string): recording from record-list --stop (boolean): stop the running replay --in-place (boolean): feed the open world instead of opening the copy --keep-world (boolean): leave the copied world in saves/ --timeout (integer): give up after this many seconds (default 300)
repro-export [NAME] [PATH] [--no-world]	repro_export	Zip a recording with the logs, crash report and status	name (string): recording from record-list (default the newest) path (string): where to write the zip --no-world (boolean): leave the world out

Replies

The reply fields of the commands described so far (more follow, a group at a time). Each reply is one JSON object; a type ending in null may be null when the field does not apply. A reader ignores keys it does not know: replies may gain fields within a protocol line. The MCP tool list declares the same fields as outputSchema.

status

Field	Type	Meaning
screen	string	the open screen (playing, inventory, paused...)
debug	object	the F3 overlay flags: overlay, hitboxes, chunk_borders, pause_menu, advanced_tooltips, pause_on_lost_focus, clipboard
dimension	string	the dimension the player is in
creative	boolean	creative mode
player	object, null	position, velocity (blocks), on_ground, health, max_health, food; null without a player
yaw	number	view yaw, degrees
pitch	number	view pitch, degrees
target	object, null	the block under the crosshair as pos and block; null when none
selected	integer	the selected hotbar slot, 1 to 9
held	object, null	the held stack as item and count; null when empty
offhand	object, null	the offhand stack as item, count and damage; null when empty
keys	array	the keys the game holds down, each a string
fps	number	frames per second
frames	integer	frames drawn so far
ticks	integer	game ticks so far
day_time	integer	the world's time of day, ticks
uptime_seconds	number	seconds since the game started
render_distance	integer	chunks
chunks	integer	chunks loaded
mobs	integer	mobs this side knows
block_entities	integer	block entities loaded
pending_chunks	integer	chunks still being generated, meshed, uploaded or received
streaming	object	chunk streaming stages and their counts
lod	object	far terrain: distances, tiles, quads and sampling progress
renderer	object, null	GPU, driver, backend, size, draw counts and GPU memory; null without a renderer
display	object, null	the monitor: width, height, scale, refresh_hz; null without a window
server	object, null	the connected server's address, name and state; null when not connected

hello

Field	Type	Meaning
protocol	string	the control protocol, MAJOR.MINOR.PATCH (docs/api/stability.md)
release	string	the game's version (MCP serverInfo carries the same string)
features	array	the command groups the game answers, each a string