CLI

turian-cli is the headless companion to Turian Studio. It scaffolds projects, prints metadata, and compiles self-contained game executables — no GUI required, which makes it ideal for continuous integration.

Commands

new-project

turian-cli new-project <path> "<Display Name>"

Scaffolds a new project directory with an assets/ folder and a starter scene.

turian-cli new-project ../my-game "My Game"

info

turian-cli info <path>

Prints the project's metadata (name, version, asset counts).

build

turian-cli build <path>

Cooks every asset into <path>/.cache/game.oap, generates build.zig + main.zig, and compiles a standalone executable at <path>/.cache/zig-out/bin/game[.exe].

The resulting binary is self-contained: it reads all assets from the sibling game.oap and needs no engine source tree to run.

package

turian-cli package <subcommand> [--project <path>] [args]

Manage a project's packages. Operates on the current directory unless --project is given.

Subcommand Description
install <source> Install a package from a local path or git URL
remove <name> Remove an installed package by its manifest name
update [name] Update a package (or all) — re-install for git sources
list List installed packages (name, version, type)
info <name> Print a package's full manifest
search <query> Search the registry (not yet available — tracked in the registry work)

See the Packages guide for the full workflow.

Building from a source checkout

If you are working inside the engine repository rather than an SDK bundle:

zig build cli -- build path/to/my-project

Path resolution

turian-cli finds the engine sources in this priority order:

  1. Environment variables — e.g. TURIAN_ENGINE_ROOT (highest priority).
  2. SDK-relative paths — resolved from the turian-sdk.json marker next to the binary.
  3. Build-time baked paths — present only in in-tree dev builds.

See Environment variable overrides for the full list.

debug

turian-cli debug <subcommand> [--host 127.0.0.1] [--port 7777] [--token <secret>]

Connects to a running game's debug server and sends JSON-RPC queries. Requires the game to have the debug module linked and the server started.

Subcommand Description
connect Ping the server (health check)
scenes List loaded scenes
inspect <name> Inspect an entity by name
entities List all entities in the active scene
component <entity> <comp> Read a component's fields
snapshot Full scene snapshot
schema Built-in component type catalog

See the Remote Debug Protocol reference for the full method list.

docs

turian-cli docs export-ai-context [--out <dir>]

Generates a self-contained AI knowledge pack without a running game. All output is derived from compile-time engine data.

Flag Default Description
--out .turian/ Output directory

Output files:

File Contents
engine-overview.md Architecture, key concepts, quick connection guide
component-schema.json All built-in component types with field definitions
mcp-tools.json MCP tool catalog with input schemas and debug method mappings
protocol-reference.json JSON-RPC method list with params and error codes
examples/list-scenes.json Example request/response pair
examples/inspect-entity.json Example request/response pair

Add to CLAUDE.md to give Claude Code offline context:

@.turian/engine-overview.md

See the MCP Integration guide for live connection setup.

mcp

turian-cli mcp [--host 127.0.0.1] [--port 7777] [--token <secret>]

Starts an MCP server (stdio transport, MCP 2024-11-05) backed by the running game's debug server. Designed to be launched by Claude Code or Cursor as an MCP subprocess.

See the MCP Integration guide for setup instructions.

Use in CI

Because build is fully headless, a typical pipeline step is just:

build-game:
  script:
    - turian-cli build .
  artifacts:
    paths:
      - .cache/zig-out/bin/

← All docs Edit this page