horizon-airdef/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
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, 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