Construct/docs/CLI.md

CLI Reference

All commands are prefixed with construct:. Arguments in angle brackets (<arg>) are required, while those in square brackets ([arg]) are optional. Assume commands can be run from any source (player, entity, block, or server) unless otherwise noted.

Instance Management

construct:create <instanceName> <structureId>

Create a new instance bound to a structure.

Argument	Description
<instanceName>	Unique name for this instance.
<structureId>	ID of a structure saved in the world (without the mystructure: prefix).

Corresponds to the "create new instance" flow in the main menu. Errors if instanceName is already taken or structureId does not exist.

construct:delete <instanceName>

Permanently delete an instance.

Argument	Description
<instanceName>	Name of the instance to delete.

Calls structureCollection.delete(). Also disables the instance and clears its saved dynamic properties before removal.

construct:rename <instanceName> <newInstanceName>

Rename an existing instance.

Argument	Description
<instanceName>	Current instance name.
<newInstanceName>	Desired new name. Errors if already in use.

construct:list

List all registered instances and their status.

Prints each instance name, its bound structure ID, enabled/disabled state, and placed location (if any). Useful for scripting and quick inspection without opening the GUI.

Placement & Movement

construct:place <instanceName> <x y z>

Enable and place an instance at a location.

Argument	Description
<instanceName>	Instance to place.
<x y z>	World coordinates. Errors if omitted. Supports tilde (~) notation.

Equivalent to the "Place" button in the instance menu — enables the instance and calls move() in one step. If the instance already has a location, this is a move, not a fresh place.

construct:move <instanceName> [x y z]

Reposition a placed instance without toggling its enabled state.

Argument	Description
<instanceName>	Name of a placed instance.
<x y z>	Target world coordinates.

Enable / Disable

construct:enable <instanceName>

Enable a placed instance.

Requires the instance to have a saved location. Refreshes the outliner, verifier, and materials cache.

construct:disable <instanceName>

Disable an active instance.

Tears down outliner rendering and pauses the verifier. The instance retains its saved location and can be re-enabled.

Layer Control

construct:layer <instanceName> <layer>

Set the active layer of an instance.

Argument	Description
<instanceName>	Name of the instance.
<layer>	Integer layer index. 0 = whole structure (no layer selected). Valid range: 0 to structure.height.

Errors if layer is out of bounds. Only meaningful for structures with height > 1.

construct:nextlayer <instanceName>

Step the layer up by one (wraps from max back to 0).

Mirrors the "Next layer" button. Wrapping from max → 0 restores the whole-structure view.

construct:prevlayer <instanceName>

Step the layer down by one (wraps from 0 back to max).

Mirrors the "Previous layer" button.

Settings

construct:verifier <instanceName> true|false

Toggle the structure verifier for an instance.

Argument	Description
<instanceName>	Name of the instance.
true|false	Whether to run the verifier. Corresponds to the "validation" toggle in Settings.

construct:option <optionId> true|false

Enable or disable a per-player builder option. Must be run as a player source.

Argument	Description
<optionId>	One of: easyPlace, fastEasyPlace, materialGrabber.
true|false	Desired state. Runs the option's enable/disable callback (gives or removes the action item).

Replaces the toggles in the Builder Options form. State is saved per-player via dynamic properties.

Information

construct:info <instanceName>

Print instance details to chat.

Outputs: bound structure ID, enabled state, placed location and dimension, current layer, verifier enabled, structure bounds (min/max). Equivalent to the data shown in the instance menu body.

construct:stats <instanceName>

Run the structure verifier and print statistics.

Triggers a standalone StructureVerifier pass (same as the "Statistics" button) and sends the result to chat. Errors if a verifier is already running on this instance.

construct:materials <instanceName> [missing]

Print the material list for an instance.

Argument	Description
<instanceName>	Name of the instance.
missing	When present, show only materials the player does not have in their inventory (mirrors the "missing only" toggle). Can only be used by a player source.

Respects the active layer: if a layer is set, only that layer's material counts are shown.

Utility

construct:item

Give yourself the Construct menu item.

Already implemented as a native custom command. Needs to be refactored to fit the new command pipeline.

construct:tag <instanceName>

Rename the held Construct item to an instance name for quick-open. Errors if the item is not a construct item or if the instance name is not registered.

Argument	Description
<instanceName>	Instance name to embed in the item's nameTag. Using the item in-world will jump straight to that instance's menu.

The item-use handler in construct.js already checks itemStack.nameTag against known instance names; this command just makes it easy to tag an item without renaming it in an anvil.