cli-reference.md

CLI command reference

This document is the current command reference for agent-dst.

The CLI is designed around a single current controlled player. In normal use you do not create or manage sessions manually. The CLI auto-selects the newest live client_player runtime and only needs --session-id when you explicitly want to override that choice.

Global flags

agent-dst [--bridge-url URL] [--session-id ID] <command>

• --bridge-url: bridge base URL, default http://127.0.0.1:3030
• --session-id: manually target a specific bridge session instead of the default live client-player session

Status and history

status

Show the selected runtime session, current player/world summary, active command, and recent meaningful events.

agent-dst status
agent-dst status --history-limit 12

history

Show recent events for the selected runtime session.

agent-dst history
agent-dst history --limit 30

Observation

look

Find entities near the player. Returns entity id, prefab, relative position (dx/dz), distance, and the ground tile under each entity (tile type + tile offset).

agent-dst look
agent-dst look --filter evergreen
agent-dst look --sort quadrant

Notes:

• radius is fixed at 20 world units (5 tiles). Use move by / move to to explore areas outside this radius — do not try to extend the look range; move closer instead.
• --sort distance (default) lists all entities nearest-first
• --sort quadrant groups entities into four directional quadrants
• each entity includes tile info: tile=FOREST(1,-1) means the entity is on a forest tile, 1 tile east and 1 tile north of the player

survey

Observe surrounding terrain as a compact ASCII grid. Each cell represents one ground tile; the player is marked with @.

agent-dst survey

Notes:

• radius is fixed at 5 tiles → produces an 11×11 square grid (1 tile = 4 world units)
• grid is square — every cell is always filled
• output includes a legend showing only tile types present in the grid
• tile characters: G=grass F=forest D=birch R=rocky S=savanna M=marsh T=dirt/desert O=ocean P=pebble beach C=cave

Movement

move to

Move the controlled player either to explicit planar coordinates or toward a resolved target entity.

Preferred coordinate form:

agent-dst move to "(-502.5,372.1)"

Other forms:

agent-dst move to --x -502.5 --z 372.1
agent-dst move to --target campfire
agent-dst move to "(12,8)" --arrival-distance 1.0
agent-dst move to --target evergreen --max-distance 18

Notes:

• tuple form is planar (x, y) for human/agent readability
• internally the tuple y maps to DST world z
• either --target or coordinates are required

move by

Move the controlled player by a relative offset from the current position.

agent-dst move by --dx 3 --dz -5
agent-dst move by --dx -2 --dz 0
agent-dst move by --north 20
agent-dst move by --east 15 --north 10
agent-dst move by --north 20 --arrival-distance 1.5

Notes:

• computes target = current position + offset, then submits a move_to command
• requires a live session with a known player position
• cardinal aliases: --north N = --dz -N, --south N = --dz +N, --east N = --dx +N, --west N = --dx -N
• --dx/--dz and cardinal flags can be combined; they are summed together

Speech

say

Send a chat message through DST chat (TheNet:Say(...)).

agent-dst say "hello everyone"
agent-dst say "psst" --whisper

Crafting and inspection

craft

Craft a recipe by recipe name or product-like name. For placer recipes, provide coordinates.

agent-dst craft axe
agent-dst craft torch
agent-dst craft campfire "(12,8)"
agent-dst craft firepit --x 12 --z 8 --rotation 90

Notes:

• non-placer recipes go through the normal crafting menu path
• placer recipes require coordinates because the runtime must pick a final placement point
• the command currently resolves by exact recipe name first, then by product name

inspect

Request a focused inspection of a nearby inspectable entity.

agent-dst inspect evergreen
agent-dst inspect campfire --max-distance 12

Interactions

interact pickup

Pick up the nearest matching target (dropped items on the ground — flint, twigs, logs, etc.).

agent-dst interact pickup flower
agent-dst interact pickup flint --max-distance 10

Notes:

• use interact harvest for berry bushes, farm crops, drying racks, and other "producer" targets that you harvest without destroying
• dispatches once and finishes when the item is gone (will not re-attempt if target becomes unavailable)

interact work

Destroy or damage a world object. The correct action (CHOP, MINE, HAMMER, DIG) is auto-detected from the target — just provide the target GUID.

agent-dst interact work 123456
agent-dst interact work 123456 --max-distance 12
agent-dst interact work 123456 --times 3
agent-dst interact work 123456 --continue

Notes:

• target must be provided as a GUID (get it from look)
• action is auto-detected: trees → CHOP, boulders → MINE, structures → HAMMER, stumps/saplings → DIG
• continues until the target is destroyed (tree falls, rock breaks) or the action becomes unavailable (tool breaks)
• --times N stops after N completed work swings/hits instead of fully depleting the target
• --continue is an explicit spelling of the default continuous work behavior
• optionally accepts --interaction-distance to fine-tune when the player stops walking before acting

interact harvest

Collect produce from a source entity without destroying it (berry bushes, farm crops, drying racks, crock pots, etc.).

agent-dst interact harvest 123456
agent-dst interact harvest 123456 --max-distance 10

Notes:

• target must be provided as a GUID (get it from look)
• tries HARVEST first, then PICK — covers both DST action types used by harvestable entities
• dispatches once and finishes when produce is collected

interact fuel

Use an inventory item on a world target with DST fuel actions (ADDFUEL, ADDWETFUEL).

agent-dst interact fuel campfire --item log
agent-dst interact fuel firepit --item boards

interact apply

Generic item-on-target interaction. This is the precise fallback when a source item must be applied to a target and there is no more specific subcommand.

agent-dst interact apply lantern --item lightbulb
agent-dst interact apply beefalohat --item sewing_kit
agent-dst interact apply lantern --item lightbulb --action ADDFUEL

Notes:

• positional target is always the destination object
• --item is always the source inventory item
• if more than one valid item-on-target action exists and --action is omitted, the command fails with an ambiguity error instead of guessing

interact give

Give an inventory item to a world target or another player-like target.

agent-dst interact give pigman --item berries
agent-dst interact give skeleton_player --item petals

Inventory

inventory list

Show current equipped items and inventory slot contents.

agent-dst inventory list

inventory equip

Equip an inventory item using DST inventory actions.

agent-dst inventory equip axe
agent-dst inventory equip torch

inventory unequip

Unequip by item query or slot-like query.

agent-dst inventory unequip axe
agent-dst inventory unequip hands
agent-dst inventory unequip body

inventory use

Trigger a self inventory action on an item. This command does not cover item-on-target usage; use interact apply for that.

agent-dst inventory use torch
agent-dst inventory use blueprint --action STUDY

Notes:

• inventory use excludes eat, drop, equip, and unequip
• if more than one remaining self action exists and --action is omitted, the command fails with an ambiguity error instead of guessing

inventory eat

Consume an edible inventory item.

agent-dst inventory eat berries
agent-dst inventory eat cookedmeat

Notes:

• inventory eat only accepts items that expose the DST EAT action
• non-food or non-edible items fail with a dedicated not_edible style error instead of falling back to generic use

inventory drop

Drop an inventory item at the current player position.

agent-dst inventory drop petals
agent-dst inventory drop flint

Containers

container open

Open a nearby container through the normal client interaction path.

agent-dst container open treasurechest
agent-dst container open icebox --max-distance 8

container close

Close an already open container. If target is omitted, the CLI/runtime will use the first matching open container.

agent-dst container close
agent-dst container close treasurechest

container store

Store an inventory item into a container target.

agent-dst container store treasurechest --item log
agent-dst container store icebox --item berries

container take

Take an item out of an already open container.

agent-dst container open treasurechest
agent-dst container take treasurechest --item log

Control

wait

Queue a timed no-op.

agent-dst wait
agent-dst wait --ms 2500

cancel

Cancel the active command, or a specific command id.

agent-dst cancel
agent-dst cancel --command-id <id> --reason "manual stop"

Bridge

bridge health

Show bridge health and session counts.

agent-dst bridge health

Currently implemented client actions

The client-player runtime currently supports:

• wait
• move_to
• craft
• inspect_entity
• look
• survey
• say
• pickup
• harvest
• work
• equip
• unequip
• use
• eat
• drop
• give
• fuel
• open_container
• close_container
• store
• take_container_item

Important actions still missing

These are the next high-value actions that still need real implementation on the client-player route:

1. attack / combat: eventually necessary, but it is riskier than the core survival loop and should come after the current interaction set is validated live.
2. richer craft workflows: recipe discovery, prototyper-aware planning, and better failure introspection are still worth improving even though the base command now exists.
3. container transfers beyond the first primitives: slot targeting, half-stack moves, and cross-container moves are still missing.
4. deploy / structure placement as a standalone semantic action: some recipes are craftable now, but general item deployment is still a separate gap.
5. machine workflows: crock pot, science interactions, and other multi-step structure flows still need higher-level commands.

Recommended near-term action roadmap

If we continue from the current shape, the next implementation batch should be:

1. combat
2. richer craft diagnostics
3. deeper container transfers
4. deploy/build workflows
5. machine-specific workflows

That order keeps the next loop focused on turning the current gather -> craft -> equip/use -> store/take baseline into a fuller survival and production agent.