@hypersoniclabs/helix-cli

helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds to the HELIX backend. It shares bundle validation with the server via @hypersoniclabs/helix-manifest, so "validate passed but publish failed" can't happen for contract reasons.

Install

npm install -g @hypersoniclabs/helix-cli

Authentication

helix login opens your browser to the website's /cli-login page; you sign in there and the CLI captures a client token via a one-shot loopback redirect. For CI/headless, pass a token directly: helix login --token <token> (mint one in the Creator Hub → Settings → Client Tokens).

The token is stored in ~/.helix/credentials.json (mode 600). It's sent as Authorization: Bearer <token> on publish calls. helix login validates it against GET /api/v1/users/me before saving and reads the token's exp so the CLI knows when it lapses.

The backend & website default to the build's environment: the published @hypersoniclabs/* CLI targets production (api.helixgame.com / helixgame.com); the staging @helixdev/* CLI targets the staging backend (helix-backend-staging.up.railway.app) + staging website (next.helixgame.com). Override per run with --api-url/HELIX_API_URL and --web-url/HELIX_WEB_URL (e.g. a local/dev backend).

Commands

| Command | What it does | |---|---| | helix login [--api-url <url>] [--web-url <url>] [--token <t>] [--no-browser] | Sign in via the browser (/cli-login), or --token for CI/headless. Stores the client token. | | helix logout | Remove the stored token. | | helix whoami | Show current login status. | | helix init <dir> | Scaffold a minimal Three.js world (helix.json + index.html + main.js). | | helix install [--update] | Resolve a world's systems/abilities pins (a v0.2 or v0.3 manifest) → materialize the modules, the three import map, and helix.runtime.ts. | | helix validate [dir] | Validate a bundle locally — the exact rules the server enforces. | | helix publish [dir] | Validate → resolve/create the world → upload files → finalize → print the play URL. | | helix list | List your worlds. | | helix doctor [--project <dir>] | Print the environment + whether the @helix toolchain (CLI/MCP/SDK/manifest) is current. |

Publish flow

helix publish maps directly onto the backend's Instant World API:

1. checkBundle validates helix.json + files via @hypersoniclabs/helix-manifest.
2. GET /api/v1/instant-worlds/me → reuse the world with the manifest's slug, else POST /api/v1/instant-worlds.
3. POST /api/v1/instant-worlds/:id/builds → presigned upload tickets.
4. Files PUT directly to storage (6 concurrent), content-type/length bound to each ticket.
5. POST /api/v1/instant-worlds/:id/builds/:buildId/finalize → byte-exact verify, activate, publish.
6. GET /api/v1/instant-worlds/:slug → the play URL.

The programmatic surface (publishWorld, checkBundle, whoAmI, …) is exported from the package main, so an MCP server can drive the exact same code paths an agent would.

Develop

npm install
npm test       # jest
npm run build  # tsc → dist/ (bin: dist/index.js)
npm run lint