glr-cli

Configure and operate the GameLearningRuntime agent-first CLI for bridge startup, bounded goal-driven research and training, concurrent review capture, run queries, spatial knowledge transfer, and verified model playback. Use for operating an existing GLR project; use glr-adapter-builder when implementing the game adapter itself.

Operate GLR through the standalone Rust control plane while preserving the adapter/learner boundary. The glr executable is the canonical deployment and Agent entrypoint; Python is an optional SDK for project roles, not a CLI runtime dependency.

Resolve bundled files portably

This Skill is distributed from both GLR releases and Agent Plugin packages. Resolve its references/ directory relative to the directory containing this SKILL.md; do not assume a repository checkout or a user-profile install path. The --skills-dir option below is a project-owned destination for an explicit update and is separate from the host's installed plugin directory.

Read references/commands.md before creating a project config, running a goal, transferring knowledge, or claiming reproduction.

Select the correct boundary

• Use this Skill when the project already has a reviewed runtime bridge and needs CLI setup or operation.
• Use glr-adapter-builder when implementing or changing observation, action, lifecycle, transport, target binding, or post-action verification.
• Never make the game adapter import a learner algorithm. The configured trainer, planner, researcher, evaluator, recorder, and player remain explicit project-owned processes.

Operate agent-first

1. Run glr --version, resolve the nearest glr-project.toml (legacy JSON is also supported), and run glr --project . --json doctor; do not guess a bridge path or game target.
2. Inspect the strict project roles and exact environment_id, environment_family, and protocol_version before execution.
3. When doctor.data.lifecycle is present, treat it as the loaded-input manifest: verify every config owner, path, schema version, and SHA-256, then use only the listed lifecycle modes. A missing mode is a shared GLR capability gap; do not create a project-local run_*.py lifecycle wrapper to bypass it.
4. When one invocation selects a configuration set, pass a reviewed --context config/contexts/NAME.toml. Treat doctor.data.run_context as the frozen glr.run-context.v1 receipt. Python roles must call load_inherited_run_context(project) before consuming selected inputs.
5. Use glr runtime start only for the configured fixed-argv runtime command. Its process exit proves command completion, not a live bridge handshake or gameplay success.
6. Express the user objective as glr.agent-goal.v1 with machine-readable success criteria and hard trial, step, time, and research-source budgets.
7. Run glr goal run. Let the project researcher gather only allowed sources; let the planner emit declarative reward terms; require the trainer/runtime to persist metrics; accept success only when evaluator evidence matches those persisted authoritative metrics.
8. Inspect glr runs show and query entities, routes, or research before deciding the next action. Route and guide results are hints; re-observe and verify postconditions in the live runtime.
9. Use a verified model bundle for playback. A valid hash proves artifact integrity and config identity, not policy quality, hardware determinism, or successful live gameplay.

Run project-local tasks through VX

• When the project contains glr.toml, run glr --project . --json task list before assuming a project workflow is missing.
• Inspect a task with glr task show NAME, then pass only declared values with repeated --set NAME=VALUE arguments.
• Prefer runner = "vx" with argv = ["uv", "run", ...] for Python training workflows. VX owns Python/tool versions and the project environment; GLR owns validation, dependency ordering, timeouts, logs, and receipts.
• A project task is not a core GLR command. Successful glr task run season proves process completion only; require authoritative run/evaluator evidence before claiming the season or gameplay objective succeeded.
• Keep season, ruleset, league, experiment, and campaign concepts in task parameters or context labels. Do not invent top-level product-specific CLI commands for them.
• Never rewrite a fixed argv task as a shell string or execute a remote task catalog. Treat glr.toml as trusted repository configuration.

Keep the managed runtime current

• glr update --check is a read-only release check and is safe to use when diagnosing version drift.
• Run glr update --yes only when the user explicitly asks to update GLR. It verifies the exact platform archive and SHA256SUMS, then updates the glr executable, its sibling glr-hostd, and the repository-owned glr-cli and glr-adapter-builder Skills.
• Use --skills-dir only for an explicitly selected project Skills directory. Use --no-skills when the user requested binary-only maintenance.
• The updater does not modify game code, project role dependencies, Python environments, models, datasets, project manifests, or trainer configuration.
• SHA-256 protects same-release artifact integrity; it is not publisher signature verification. Report the first unified-release smoke boundary when no matching target archive exists yet.
• Public checks use GitHub's latest-release asset link rather than the REST API, so they do not consume anonymous API quota. The updater derives the version, exact target archive, and digest from the published SHA256SUMS.

Preserve knowledge scope

On a knowledge-enabled decision, persist the injector's query fingerprint, trigger/hit counts, selection counts, and rejection counters with the step. No invocation, a valid zero-hit lookup, and a rejected stale source are distinct states. Knowledge-file presence is not a trigger or a hit; a hit is not learning.

• Environment-scoped positions and routes transfer only across the exact environment and protocol. Imports are downgraded to advisory until the new runtime observes them again.
• Family-scoped tutorial/guide findings may inform a similar game, but never transfer coordinates, action authority, or model compatibility.
• Keep public source provenance, access time, compact paraphrases, confidence, volatility, and runtime-verification status. Never store credentials or full copied guides.
• Exclude rejected findings. Treat unverified findings as hypotheses, never authoritative reward or success evidence.

Portable project handoff

New projects use a single glr-project.toml. Before migration, verify the installed CLI and Python SDK support TOML; unreleased source changes do not upgrade installed tools. Never leave JSON and TOML manifests side by side. Use GLR_PROJECT_MANIFEST or find_project() to locate the project; resolve relative config paths from its parent, not cwd or a fixed number of parents. Read the portable layout and clone gates in commands.md when scaffolding, migrating environments, or handing a project to another user.

Recording and training data

When capture is configured, keep it enabled for glr train and glr goal run unless the user explicitly opts out. The recorder is a concurrent project-owned sidecar and must emit both a small H.264 MP4 and glr.capture-frame.v1 step/frame index. A video without a valid checksummed index is review media, not supervised-learning data.

Do not claim live-game acceptance from synthetic tests, process exit, video presence, run status, or model hashes. Report the exact remaining runtime acceptance boundary.

Build an offline run report

Generate a self-contained, interactive review page from one completed run:

powershell

glr --project . --json report build <run-id>
glr --project . --json report build <run-id> --output review/report

The default output is .glr/runs/<run-id>/report/index.html; a custom output must remain inside that run directory. Before writing, GLR verifies every registered evidence artifact's portable path, byte size, and SHA-256 digest, omits prior run-report outputs to avoid self-referential hashes, then registers the HTML as a run-report artifact. The page is offline and filterable: it summarizes metrics, renders navigation.route_sample points, shows progression.* unlock/catalog events, lists explicit match.result records (including match_kind=pvp), and links authorized screenshots or videos by their checksummed artifact paths.

Reports are projections over the run store, not a second source of truth. They do not mutate training data, infer missing unlocks or wins, widen action masks, or establish live-game acceptance. Keep unsupported panels empty and return to the adapter/runtime boundary when authoritative evidence is missing.