CLI & AI toolsCommand reference
helix achievement
Register and manage a world's achievements (the badges `awardAchievement` and criteria unlocks grant)
CLI version 0.1.27-helix3.551. Run
helix achievement --help for the text your installed build prints.helix achievement
Register and manage a world's achievements (the badges awardAchievement and criteria unlocks grant)
helix achievement <command>helix achievement register
Register a new achievement on one of your worlds — one round trip, mints the soulbound badge item
helix achievement register [options] <world-slug>| Argument | Required | Description |
|---|---|---|
world-slug | yes | the world that issues the achievement |
| Option | Description |
|---|---|
--key <key> | stable slug your rules name (2-80 chars, lowercase a-z0-9_-); treat it as a schema — renaming needs a fresh registration (required) |
--name <name> | badge title players see (required) |
--icon <file> | the 2D graphic (png/jpg/webp/gif/avif/heic) — REQUIRED, and a blank or tiny placeholder is refused (required) |
--description <text> | what the player did to earn it |
--points <n> | gamerscore points, 0-1000 (default 0) |
--hidden | show "???" until the player earns it |
--trophy <file.glb> | bespoke 3D trophy; omitted, your icon is baked onto the default plaque |
--unlock-mode <mode> | who may award it: room | criteria | platform (default: criteria when a condition is declared, else room) |
--signal <signal> | server-measured condition: datastore | iwp | analytics | playtime — declaring one makes this a criteria achievement |
--op <op> | comparison: gte | lte | eq (default gte) |
--value <n> | threshold the measured value is compared against |
--criteria-key <template> | datastore only — which per-user document: player:{userId} | mp:player:{userId} (mp: = room-written, trustworthy) |
--criteria-field <path> | datastore only — dot-path to the number (e.g. stats.summits); for mp:player it names the persistent playerVar |
--event <name> | analytics only — the platform analytics event to count (e.g. world_entered) |
--metric <metric> | iwp only: count | lix (default count) |
--dry-run | validate everything locally and print what WOULD be sent; no network, works logged out |
--json | machine-readable output |
helix achievement list
List a world's registered achievements — run it before publishing rules, to check every awarded key exists
helix achievement list [options] <world-slug>| Argument | Required | Description |
|---|---|---|
world-slug | yes | the world that issues the achievements |
| Option | Description |
|---|---|
--json | machine-readable output |
helix achievement update
Patch a registered achievement. The key, unlock mode and criteria are fixed at registration — rules name the key, and re-labelling how a badge is earned would rewrite what every granted copy claims
helix achievement update [options] <world-slug> <key>| Argument | Required | Description |
|---|---|---|
world-slug | yes | the world that issues the achievement |
key | yes | the achievement key |
| Option | Description |
|---|---|
--name <name> | new title |
--description <text> | new description |
--points <n> | new gamerscore points, 0-1000 |
--hidden <true|false> | show "???" until earned |
--active <true|false> | false delists it — existing holders keep theirs, nobody new can earn it |
--json | machine-readable output |
helix achievement set-icon
Replace an achievement's 2D graphic and re-bake the default plaque. Use THIS, not the universal-items asset route — that one suspends the achievement
helix achievement set-icon [options] <world-slug> <key> <image>| Argument | Required | Description |
|---|---|---|
world-slug | yes | the world that issues the achievement |
key | yes | the achievement key |
image | yes | the new 2D graphic (png/jpg/webp/gif/avif/heic) |
| Option | Description |
|---|---|
--json | machine-readable output |