Command Line¶

World Toolkit adds its own commands to the Unity command line (CLI). They run inside the open editor, so scripts, build pipelines and AI coding agents can create, list, check, change and rebuild World Toolkit content (terrains, roads, splines, spawners, buildings and meshes) without clicking through the editor. They're also how an agent can look at what it made: render it to images, measure it, and compare it with a reference picture.

Requirements¶

• The Unity CLI (the unity command).
• The Unity Pipeline package in your project. Add it from Window > Package Manager with + > Install package by name... and the name com.unity.pipeline.
• The Unity editor open on the project. The commands talk to the running editor; they don't start one.

World Toolkit only compiles its commands when the package is installed. Without it, nothing is added and nothing else in World Toolkit changes. So if the commands are missing, check the package first.

Running a command¶

unity cmd wtk_buildings_list

Arguments are written --name value. Lists and points are JSON arrays, in single quotes so the shell passes them unchanged:

unity cmd wtk_modelling_find_components --target "/Knob" --kind faces --normal '[0,1,0]'

Add --json for machine-readable output. Commands stop after 30 seconds by default; raise that with --timeout <seconds>, or run long ones as jobs (see Long commands).

Listing the commands¶

unity cmd --tag worldtoolkit --detail compact

lists every World Toolkit command with its description. Narrow it to one group with --tag worldtoolkit/<group>:

--query <text> finds commands by name or description and shows their argument names. For a full, machine-readable list with every argument and result, see wtk_manifest.

Pointing at objects¶

Arguments that take an object (--target, --road, --spline, --parent...) accept any one of these forms:

Commands that list or create objects return their hierarchy path and global ID. Use the global ID when two objects share a name: a hierarchy path takes the first match across all open scenes.

A few arguments take several objects at once (--objects, --terrains, --targets). They're JSON lists of hierarchy paths or global IDs, such as '["/Spline A", "/Spline B"]'.

Long commands¶

Add --detach to start a command as a job and get its ID right away, then follow it with unity job status <id> or unity job wait <id>. Use this for wtk_buildings_audit with --thoroughness thorough on large buildings, which can take tens of seconds.

Safe by default¶

• Commands marked read-only below never change the scene. Renders are made from an offscreen copy.
• Commands that change objects can be undone with Ctrl+Z, and they leave the changed scene unsaved. Only the scene commands save scenes, and only the scene you name. Commands that write new assets (presets, rules, terrain data) say so in their description.
• Commands that create or change content finish its rebuild before they return, so the next command, render or check sees the result.
• Overwriting a file or throwing away changes needs --confirm true.
• --dry_run true, where available, reports what a command would do without doing it.
• Images go to a new folder under the project's Temp/WorldToolkitCommands unless you pass --output_dir.

Any World Toolkit object¶

Commands that work the same way on every module (tag worldtoolkit/catalog). An agent can find what's in the project and the open scenes, understand it, and change it, without knowing each module's inspector.

unity cmd wtk_properties_get --target '{"hierarchyPath":"/Rock Patch"}' --path "layers[0]"
unity cmd wtk_properties_set --target '{"hierarchyPath":"/Rock Patch"}' --values '{"layers[0].maskComposition": [{"$type": "TerrainCircleStampMask"}], "layers[0].stamps[0].terrainLayer": "Assets/Terrain/Rock.terrainlayer"}'

The command manifest¶

wtk_manifest describes every World Toolkit command in one JSON document: its description, its group, whether it's read-only or undoable, each argument's type, default and whether it's required, and the shape of its result. It's generated from the commands themselves, so it always matches the version installed.

The editor also writes the manifest to Library/WorldToolkit/AgentManifest.json in the project after every script compilation. A tool or agent can read that file to see what it can call, without waiting for the editor to answer. --output_file writes a copy anywhere else; --tag limits the manifest to one group.

Inspection¶

Commands that work on any scene object or prefab (tag worldtoolkit/inspection).

Terrain¶

Commands for terrain stamps (tag worldtoolkit/terrain). wtk_describe, wtk_validate and wtk_rebuild also work on stamp targets, stamps, terrains and stamp presets.

Splines¶

Commands for spline containers and link groups (tag worldtoolkit/splines). Everything built on a spline (roads, stamps, spawners, buildings) follows it: after a change, these commands finish those rebuilds before returning.

Paths are JSON. Positions are in world space unless you pass --space local:

[
  {"knots": [[0, 0, 0], [20, 0, 0], [40, 0, 10]], "closed": false},
  {"knots": [[0, 0, 30], {"position": [20, 0, 30], "tangentMode": "Linear"}]}
]

A knot is [x, y, z], or an object with position and, optionally, tangentMode (Linear, AutoSmooth, Mirrored, Broken, Continuous), tension, rotation, tangentIn and tangentOut. A single path can be given without the outer list, and a bare list of knots is one open path.

Roads¶

Commands for roads and junctions (tag worldtoolkit/roads). wtk_describe, wtk_validate and wtk_rebuild also work on roads, junctions, road rules and profiles.

Road ends are written as {"road": "/Road", "path": 0, "end": "start"} (or "end"). The road can be a handle string, as here, or a handle object such as {"hierarchyPath": "/Road"}. Use {"road": ..., "path": 0, "knot": 3} instead to join a junction at a knot in the middle of a road. wtk_describe on a road lists its ends and the junction each one meets.

unity cmd wtk_roads_create --name "Main Street" --paths '[[0,0,0],[80,0,0]]'
unity cmd wtk_roads_create --name "Side Street" --paths '[[40,0,60],[40,0,10]]'
unity cmd wtk_roads_connect --endpoints '[{"road":"/Side Street","end":"end"}]' --to_road '{"hierarchyPath":"/Main Street"}' --at '[40,0,0]'

Spawners¶

Commands for the Array Spawner and Area Spawner (tag worldtoolkit/spawners). wtk_describe, wtk_validate and wtk_rebuild also work on spawners and Spline Array Rules.

Buildings¶

Commands for buildings (tag worldtoolkit/buildings).

wtk_buildings_validate and wtk_buildings_audit work well as automatic content checks, for example before a build.

Modelling¶

Commands that create and edit Editable Meshes without using the editor selection (tag worldtoolkit/modelling).

The four create commands take their shape as JSON, from a file (--input_file, absolute or relative to the project folder) or inline (--definition). Their descriptions in the command list name every field. Pass --target with an existing Editable Mesh to rebuild it in place, keeping its transform, children and references.

{
  "profile": [[0, 0], [0.4, 0], [0.4, 0.3], [0.25, 0.5], [0, 0.5]],
  "segments": 24,
  "hard_points": [1, 2]
}

unity cmd wtk_modelling_create_revolve --input_file knob.json --name Knob
unity cmd wtk_modelling_find_components --target "/Knob" --kind faces --normal '[0,1,0]' --max_angle 10
unity cmd wtk_modelling_apply --target "/Knob" --operation extrude --distance 0.1 --faces '[3,7,11,15,19,23]'
unity cmd wtk_render_views --target "/Knob" --mode wireframe

Scenes and sessions¶

Commands for working beside someone who is using the editor at the same time, typically an AI agent (tag worldtoolkit/session). They keep the agent's work in its own scene and away from the user's.

AI agents¶

Coding agents that can run shell commands (Claude Code, Codex, Cursor and similar) can use these commands as they are. Point the agent at the listing command above, or at the command manifest: each description says what the command does, what it returns and which arguments it takes, and was written for an agent to read.

A typical loop for an agent:

1. Find what exists with wtk_types, wtk_objects_list and wtk_assets_list, and reuse the project's presets, profiles and rules.
2. Create content with the module commands, or change it with wtk_properties_set.
3. Understand and check it with wtk_describe and wtk_validate.
4. Look at it with wtk_render_views.

When an agent works in the editor while you do:

• Have it create its own scene with wtk_scene_create and build there, so your open scenes stay untouched.
• Turn on wtk_session_configure --isolate_undo true, and let it use wtk_scene_checkpoint and wtk_scene_restore for its own undo.
• Ask it to check its results with wtk_render_views, wtk_render_compare and the validate and audit commands, instead of guessing from numbers.
• If it changes World Toolkit objects with Unity's own commands, have it run wtk_settle before checking the result.

Known limitations¶

• Windows PowerShell 5.1 strips the double quotes inside arguments it passes to other programs, so JSON like '{"hierarchyPath":"/Villa"}' arrives broken. Use a hierarchy path or global ID without JSON, or run the command from another shell.
• Git Bash rewrites arguments that start with / into Windows paths ("/Knob" becomes C:/Program Files/Git/Knob). Set MSYS_NO_PATHCONV=1 before the command, or use the object's global ID.
• Large shapes go in a file. The Windows command line has a length limit that large vertex lists exceed. For big meshes, splines, point lists and settings, use the file form of the argument (--input_file, --paths_file, --points_file, --values_file).
• Projected patches land on the faces of the surface that face the projection direction only, and an outline that touches itself can fail to fill.
• Open revolves, made with less than a full turn, face away from the axis.