Playing a scene

Playing a scene

Prerequisites

• Python 3.11+
• Docker Engine with Compose v2 (docker compose)
• The Yanjú CLI (uv tool install yanju)

Commands

Command	What it does
yanju check	Docker ping and a light resource check. Pulls images for the current workspace scene if one is initialized.
yanju scene	List the catalog and pick one. --all lists without initializing.
yanju init <id>	Copy the editable surface into the current directory and write a candidate README. --force replaces an existing workspace.
yanju play	Start or recreate the stack, run hidden tests, stop containers if they fail.
yanju play --persist	Start and leave the stack running. --follow streams logs.
yanju logs	Tail captured logs (Ctrl+C detaches). --no-follow dumps once.
yanju status	Container health, ports, CPU/memory, whether k6 is running.
yanju verify	Hidden pytest against the scene verify.base_url.
yanju stop	Tear down containers; keep your files and logs.
yanju reset	Tear down containers and restore files to the init commit.

After you edit files, run yanju play again so the stack recreates and hidden tests run. You do not need to restart Docker by hand.

What gets copied

yanju init copies only the paths listed in that scene’s workspace.copy (usually app or nginx files plus docker-compose.yaml). It also writes a README from the scene brief.

These stay in the scene checkout and are not copied:

• eval/
• chaos/
• load/
• docker-compose.k6.yaml
• images/

Pointing at a local clone

export YANJU_SCENES_DIR=/path/to/yanju-scenarios
yanju init broken-proxy

Remote override (clone into cache):

export YANJU_SCENES_REPO=https://github.com/xyluz/yanju-scenarios.git
export YANJU_SCENES_REF=main