The Alignment League Benchmark (ALB) is a suite of multi-agent games, designed to measure how well AI agents align, coordinate, and collaborate with others (both AIs and humans).
CoGames is the games environment for ALB. You can use it to:
- create new games
- train agents to play existing ALB games
- submit those agents to the ALB leaderboard
There's one ALB game right now: Cogs vs Clips.
Install cogames as a Python package.
pip install cogamesUsing uv
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a virtual environment
uv venv .venv
source .venv/bin/activate
# Install cogames
uv pip install cogamesUsing Docker
# Ensure Python 3.12 is available
FROM python:3.12-slim
# Ensure C/C++ compiler is available
RUN apt-get update && \
apt-get install -y --no-install-recommends build-essential && \
rm -rf /var/lib/apt/lists/*
# Install cogames
RUN pip install --no-cache-dir cogamesUsing Colab
Start with cogames play. This is the default command for running a local episode.
cogames play -m arena -p starter -r log -s 300If your environment supports GUI rendering and you want the guided onboarding flow, run:
cogames tutorial playThe tutorial opens a new window, and the terminal gives you instructions for the training mission.
Command guide:
cogames play: first local run; one episode with GUI, unicode, or log renderingcogames scrimmage: repeat one policy across many episodescogames pickup: compare one policy against a pool and compute VOR; use this later, not as the default "play the game" command
-
Log into the ALB leaderboard with your GitHub account.
cogames auth login
-
Create, upload, and submit a starter bundle.
cogames create-bundle -p class=cogames.policy.starter_agent.StarterPolicy -o submission.zip cogames upload -p ./submission.zip -n "$USER.README-quickstart-starter-policy" --no-submit cogames submit "$USER.README-quickstart-starter-policy" --season beta-teams-small
-
Check your submission status.
cogames submissions --season beta-teams-small --policy "$USER.README-quickstart-starter-policy" cogames season matches beta-teams-small --limit 5
To learn more, see:
- Creating a policy: Creating a custom policy and evaluating it
- Training: Training a custom policy and evaluating it
- Submitting: Submitting to the leaderboard and understanding the results
If you want help, or to share your experience, join the Discord.
CvC is a cooperative territory-control game. Teams of AI agents ("Cogs") work together to capture and defend junctions against automated opponents ("Clips") by:
- gathering resources and depositing them at controlled junctions
- acquiring specialized roles (Miner, Aligner, Scrambler, Scout) at gear stations
- capturing neutral junctions using Aligners (costs 1 heart)
- disrupting enemy junctions using Scramblers (costs 1 heart)
- defending territory from Clips expansion
Read MISSION.md for a thorough description of the game mechanics.
There are many mission configurations available, with different map sizes, junction layouts, and game rules.
Overall, CvC aims to present rich environments with:
- Territory control: Capture and defend junctions to score points each tick
- Role specialization: Four roles (Miner, Aligner, Scrambler, Scout) with distinct capabilities and dependencies
- Dense rewards: Agents receive reward every tick proportional to territory controlled
- Partial observability: Agents have limited visibility of the environment
- Required multi-agent cooperation: No single role can succeed alone; Miners need Aligners to capture junctions, Aligners need Miners for resources, Scramblers must clear enemy territory for Aligners to advance
We run multiple tournament seasons at a time, and each has a different structure. Our freeplay seasons are cheap to submit to and evergreen: we give you indicative scores, showing how you play with others. Our team tournaments support limited submissions and usually follow this pattern:
- Play-ins: New submissions are evaluated in one or more early stages, with eliminations based on stage results.
- Team stages: Surviving policies are sampled into teams and evaluated in repeated team matches.
- Progressive culling: Lower-performing teams/policies are removed across later stages.
- Final scoring: Remaining policies are ranked on the season leaderboard using season-specific scoring.
To inspect the exact rules for a specific season:
cogames season list
cogames season show <SEASON>
cogames season stages <SEASON>
cogames season progress <SEASON>
cogames season teams <SEASON>
cogames season leaderboard <SEASON>
cogames season leaderboard <SEASON> --pool <POOL> --type team
cogames season leaderboard <SEASON> --pool <POOL> --type score-policies
cogames season pool-config <SEASON> <POOL>Note: cogames season show takes only one positional argument (<SEASON>).
Use separate subcommands (stages, progress, teams, leaderboard) for details.
The tournament API is documented at api.observatory.softmax-research.net/docs. The interactive OpenAPI spec describes all public endpoints for seasons, matches, leaderboards, and submissions.
Recommended end-to-end sequence once you are ready to submit:
# 1) Login
cogames auth login
# 2) Pick a season
cogames season list
cogames season show <SEASON>
# 3) Create a submission bundle
cogames create-bundle -p <POLICY_OR_CHECKPOINT> -o submission.zip [-f <EXTRA_PATH> ...] [--setup-script <SETUP_SCRIPT.py>]
# 4) Upload the bundle
cogames upload -p ./submission.zip -n <POLICY_NAME> --no-submit
# 5) Submit to the season
cogames submit <POLICY_NAME[:vN]> --season <SEASON>
# 6) Track status
cogames submissions --season <SEASON> --policy <POLICY_NAME>
cogames season matches <SEASON> --limit 20
# 7) Debug specific outcomes
cogames matches <MATCH_ID>
cogames match-artifacts <MATCH_ID>
cogames episode show <EPISODE_ID>
cogames episode replay <EPISODE_ID>If your policy needs credentials at runtime (e.g. an API key for an LLM provider), use --secret-env to attach
secret environment variables to your upload:
cogames upload \
-p ./my_policy -n my-llm-policy \
--secret-env ANTHROPIC_API_KEY=sk-ant-... \
--secret-env OTHER_SECRET=valueSee POLICY_SECRETS.md for details on how secrets are stored, scoped, and cleaned up.
To specify a MISSION, you can:
- Use a built-in mission name (e.g.
training_facility_1). - Use a path to a mission configuration file (e.g.
path/to/mission.yaml).
To specify a POLICY, use one of two formats:
-
URI format (for checkpoint bundles):
- Point directly at a checkpoint bundle (directory or
.zipcontainingpolicy_spec.json) - Examples:
./train_dir/my_run:v5,./train_dir/my_run:v5.zip,s3://bucket/path/run:v5.zip - Use
:latestsuffix to auto-resolve the highest version:./train_dir/checkpoints:latest
- Point directly at a checkpoint bundle (directory or
-
Key-value format (for explicit class + weights):
class=: Policy shorthand or full class path fromcogames policies, e.g.class=lstmorclass=cogames.policy.random.RandomPolicy.data=: Optional path to a weights file (e.g.,weights.safetensors). Must be a file, not a directory.proportion=: Optional positive float specifying the relative share of agents that use this policy (default: 1.0).kw.<arg>=: Optional policy__init__keyword arguments (all values parsed as strings).
You can view all the commands with
cogames --helpand you can view help for a given command with:
cogames [COMMAND] --helpUsage: cogames play [OPTIONS]
Play a game interactively. This runs a single episode of the game using one or more policies. By default, the policy is 'noop', so agents won't move unless manually controlled. To see agents move by themselves, use `--policy class=random` or `--policy class=baseline`. Multiple -p flags assign one policy per team (in team order). You can manually control the actions of a specific cog by clicking on a cog in GUI mode or pressing M in unicode mode and using your arrow or WASD keys. Log mode is non-interactive and doesn't support manual control.
╭─ Game Setup ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --game GAME Game to play (default: cogsguard). [default: cogsguard] │ │ --mission -m MISSION Mission to play, or a path to a mission config file. │ │ --variant -v VARIANT Apply variant modifier (repeatable). │ │ --cogs -c N Number of cogs/agents. [default: (from mission)] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Policy per team. One -p applies to all teams; multiple -p assigns one per team. │ │ --device DEVICE Policy device (auto, cpu, cuda, cuda:0, etc.). [default: auto] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Simulation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --steps -s N Max steps per episode (note: -s is steps, not seed). │ │ [default: 1000] │ │ --action-timeout-ms MS [x>=1] Max ms per action before noop. [default: 10000] │ │ --render -r [auto|gui|unicode|log|none] auto=gui when display is available, otherwise │ │ unicode; gui=MettaScope, unicode=terminal, │ │ log=metrics only. │ │ [default: auto] │ │ --seed INTEGER RNG seed for reproducibility (use --seed, not -s). │ │ [default: 42] │ │ --map-seed SEED Separate seed for procedural map generation. │ │ [default: (same as --seed)] │ │ --autostart Start simulation immediately without waiting for user │ │ input. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --save-replay-dir DIR Save replay file for later viewing with cogames replay. │ │ --save-replay-file FILE Save replay to a fixed file path (overwrites existing file) │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames play -m arena Interactive cogames play -m arena -p class=random Random policy cogames play -m arena -c 4 -p class=baseline Baseline, 4 cogs cogames play -m four_score -p nlanky -p baseline -p random -p noop One policy per team cogames play -m four_score -p nlanky:1 -p random:2 Mixed teams (cycling pattern) cogames play -m arena --save-replay-file ./latest.json.z Overwrite fixed replay file cogames play -m machina_1 -v talk -r gui Speech bubbles over cogs cogames play -m machina_1 -r unicode Terminal mode
Usage: cogames replay [OPTIONS] FILE
Replay a saved game episode from a file in the GUI.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * replay_path FILE Path to a MettaGrid replay (.json.z, .replay, .bin) or a BitWorld replay │ │ (.bitreplay). │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ │ --duration FLOAT Seconds to keep a BitWorld replay server alive. MettaScope replays ignore this │ │ option. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames replay ./replays/game.json.z Replay Cogs vs Clips in MettaScope cogames replay ./train_dir/my_run/replay.bin Replay a legacy MettaGrid run cogames replay ./among_them.bitreplay Replay BitWorld in the global client
Usage: cogames scrimmage [OPTIONS]
Evaluate a single policy controlling all agents.
This command is equivalent to running `cogames run` with a single policy.
╭─ Mission ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --mission -m MISSION Missions to evaluate (supports wildcards). │ │ --cogs -c N Number of cogs (agents). │ │ --variant -v VARIANT Mission variant (repeatable). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Policies to evaluate: (URI[,proportion=N] or NAME or │ │ class=NAME[,data=FILE][,proportion=N]...). │ │ --device DEVICE Policy device (auto, cpu, cuda, cuda:0, etc.). [default: auto] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Simulation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --episodes -e N [x>=1] Number of evaluation episodes. [default: 10] │ │ --steps -s N [x>=1] Max steps per episode (note: -s is steps, not seed). │ │ [default: (from mission)] │ │ --seed N [x>=0] Seed for evaluation RNG (use --seed, not -s). [default: 42] │ │ --map-seed N [x>=0] MapGen seed for procedural maps. [default: (same as --seed)] │ │ --action-timeout-ms MS [x>=1] Max ms per action before noop. [default: 250] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --format FMT Output format: yaml or json. │ │ --save-replay-dir DIR Directory to save replays. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames scrimmage -m arena -p lstm Single policy eval
Usage: cogames run [OPTIONS]
Evaluate one or more policies on missions. With multiple policies (e.g., 2 policies, 4 agents), each policy always controls 2 agents, but which agents swap between policies each episode. With one policy, this command is equivalent to `cogames scrimmage`.
╭─ Mission ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --mission -m MISSION Missions to evaluate (supports wildcards). │ │ --cogs -c N Number of cogs (agents). │ │ --variant -v VARIANT Mission variant (repeatable). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Policies to evaluate: (URI[,proportion=N] or NAME or │ │ class=NAME[,data=FILE][,proportion=N]...). │ │ --device DEVICE Policy device (auto, cpu, cuda, cuda:0, etc.). [default: auto] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Simulation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --episodes -e N [x>=1] Number of evaluation episodes. [default: 10] │ │ --steps -s N [x>=1] Max steps per episode (note: -s is steps, not seed). │ │ [default: (from mission)] │ │ --seed N [x>=0] Seed for evaluation RNG (use --seed, not -s). [default: 42] │ │ --map-seed N [x>=0] MapGen seed for procedural maps. [default: (same as --seed)] │ │ --action-timeout-ms MS [x>=1] Max ms per action before noop. [default: 250] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --format FMT Output format: yaml or json. │ │ --save-replay-dir DIR Directory to save replays. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames run -m arena -p lstm Evaluate single policy cogames run -m machina_1 -p ./train_dir/my_run:v5 Evaluate a checkpoint bundle cogames run -m 'arena.*' -p lstm -p random -e 20 Evaluate multiple policies together cogames run -m machina_1 -p ./train_dir/my_run:v5,proportion=3 -p class=random,proportion=5 Evaluate policies in 3:5 mix
Usage: cogames pickup [OPTIONS]
Evaluate a policy against a pool of other policies and compute VOR.
╭─ Mission ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --mission -m MISSION Mission to evaluate on. [default: arena] │ │ --cogs -c N [x>=1] Number of cogs (agents). [default: 4] │ │ --variant -v VARIANT Mission variant (repeatable). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Candidate policy to evaluate. │ │ --pool POLICY Pool policy (repeatable). │ │ --device DEVICE Policy device (auto, cpu, cuda, cuda:0, etc.). [default: auto] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Simulation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --episodes -e N [x>=1] Episodes per scenario. [default: 1] │ │ --steps -s N [x>=1] Max steps per episode (note: -s is steps, not seed). [default: 1000] │ │ --seed N [x>=0] Base random seed (use --seed, not -s). [default: 50] │ │ --map-seed N [x>=0] MapGen seed for procedural maps. [default: (same as --seed)] │ │ --action-timeout-ms MS [x>=1] Max ms per action before noop. [default: 250] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --save-replay-dir DIR Directory to save replays. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames pickup -p greedy --pool random Test greedy against pool of random
Usage: cogames diagnose [OPTIONS]
Run diagnostic evals for a policy checkpoint.
Examples: cogames diagnose ./train_dir/my_run Default CvC evals cogames diagnose lstm --scripted-baseline-policy scripted.basic Compare against scripted baseline cogames diagnose lstm --known-strong-policy my_best_policy Normalize against known-strong policy cogames diagnose lstm --compare-run-dir outputs/cogames-diagnose/prev_run Stability comparison
Usage: cogames version [OPTIONS]
Show version information for cogames and dependencies.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames docs [OPTIONS] DOC
Print documentation (run without arguments to see available docs).
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ doc_name DOC Document name (amongthem_policy, mission, readme, scripted_agent, technical_manual). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames docs List available documents cogames docs readme Print README cogames docs mission Print mission briefing
Usage: cogames policies [OPTIONS]
Show available policy shorthand names.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: Use these shorthand names with --policy or -p: cogames play -m arena -p class=random Use random policy cogames play -m arena -p class=baseline Use baseline policy
Usage: cogames create-bundle [OPTIONS]
Create a submission bundle zip from a policy.
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --policy -p POLICY Policy specification: URI (bundle dir or .zip) or NAME or │ │ class=NAME[,data=FILE][,kw.x=val]. │ │ [required] │ │ --init-kwarg -k KEY=VAL Policy init kwargs (can be repeated). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --output -o PATH Output path for the bundle zip. [default: submission.zip] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Files ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --include-files -f PATH Files or directories to include (can be repeated). │ │ --setup-script PATH Python setup script to include in the bundle. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames create-bundle -p <POLICY_OR_CHECKPOINT> -o submission.zip Create a submission bundle cogames create-bundle -p <POLICY_OR_CHECKPOINT> -o submission.zip -f <EXTRA_PATH> ... --setup-script <SETUP.py> Include extra runtime files or setup when needed
Usage: cogames validate-bundle [OPTIONS]
Validate a policy bundle runs correctly in Docker.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --policy -p URI Bundle URI (file://, s3://, or local path to .zip or directory). [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tournament ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season SEASON Tournament season (determines which game to validate against). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --server URL Tournament server URL (used to resolve default season). │ │ [default: https://api.observatory.softmax-research.net] │ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Validation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --image TEXT Docker image for container validation. [default: ghcr.io/metta-ai/episode-runner:latest] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames submissions [OPTIONS]
Show your uploads and tournament submissions.
╭─ Filter ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Filter by policy name (e.g., 'my-policy' or 'my-policy:v3'). │ │ --season SEASON Filter by tournament season. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON instead of table. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames submissions All your uploads cogames submissions --season beta-cvc Submissions in a season cogames submissions -p my-policy Info on a specific policy
Usage: cogames leaderboard [OPTIONS] SEASON
Show tournament leaderboard for a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ season_arg SEASON Tournament season name (positional shorthand for --season). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tournament ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season SEASON Tournament season name (default: server default). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filter ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -P POLICY Filter by policy name (e.g., 'slanky' or 'slanky:v88'). │ │ --mine -M Show only your own policies (requires auth). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON instead of table. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames leaderboard beta-cvc View rankings (positional season) cogames leaderboard --season beta-cvc View rankings (option) cogames leaderboard beta-cvc --policy slanky Filter by policy name cogames leaderboard beta-cvc --mine Show only your policies
Usage: cogames matches [OPTIONS] MATCH_ID
Show your recent matches and policy logs.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ match_id TEXT Match ID to show details for. If omitted, lists recent matches. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filter ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season -s SEASON Tournament season (for listing matches). │ │ --policy -P POLICY Filter matches to those involving a specific policy (e.g., 'slanky' or 'slanky:v88'). │ │ --limit -n N Number of matches to show. [default: 20] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --logs -l Show available policy logs for the match. │ │ --download-logs -d DIR Download all accessible logs to directory. │ │ --json Print raw JSON instead of table. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames matches List recent matches cogames matches --policy slanky Filter by policy name cogames matches <match-id> Show match details cogames matches <match-id> --logs Show available logs cogames match-artifacts <match-id> error-info Show runner error info cogames matches <match-id> -d ./logs Download logs
Usage: cogames match-artifacts [OPTIONS] MATCH_ID ARTIFACT_TYPE
Retrieve artifacts for a match (logs, etc.).
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * match_id TEXT Match ID to fetch artifacts for. [required] │ │ artifact_type TEXT Type of artifact to retrieve (e.g. 'logs', 'error-info'). [default: logs] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Filter ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY_VERSION_ID Policy version ID. If omitted, uses your first policy in the match. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --output -o FILE Save artifact to file. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames match-artifacts <match-id> Get match logs cogames match-artifacts <match-id> error-info Get runner error info cogames match-artifacts <match-id> logs -o out.txt Save to file
Usage: cogames upload [OPTIONS]
Upload a policy to CoGames.
╭─ Upload ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --name -n NAME Name for your uploaded policy. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --policy -p POLICY Policy specification: URI (bundle dir or .zip) or NAME or │ │ class=NAME[,data=FILE][,kw.x=val]. │ │ [required] │ │ --init-kwarg -k KEY=VAL Policy init kwargs (can be repeated). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Files ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --include-files -f PATH Files or directories to include (can be repeated). │ │ --setup-script PATH Python setup script to run before loading the policy. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Secrets ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --secret-env KEY=VALUE Secret environment variable for policy execution (can be repeated). Stored in │ │ AWS Secrets Manager. │ │ --use-bedrock Enable AWS Bedrock access for this policy. Sets USE_BEDROCK=true in policy │ │ environment. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tournament ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season SEASON Tournament season (default: server's default season). │ │ --no-submit Upload without submitting to a season. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Validation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --dry-run Run the Docker smoke test only without uploading. │ │ --skip-validation Skip the Docker smoke test. │ │ --image TEXT Docker image for container validation. │ │ [default: ghcr.io/metta-ai/episode-runner:latest] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames upload -p ./submission.zip -n my-policy --no-submit Upload a submission bundle without submitting cogames upload -p ./submission.zip -n my-policy --dry-run Validate a submission bundle locally without uploading
Usage: cogames submit [OPTIONS] POLICY
Submit a policy to a tournament season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * policy_name POLICY Policy name (e.g., 'my-policy' or 'my-policy:v3' for specific version). │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tournament ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season SEASON Tournament season name. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames submit my-policy Submit to default season cogames submit my-policy:v3 --season beta-cvc Submit specific version to specific season
Usage: cogames ship [OPTIONS]
Bundle, validate, upload, and submit a policy in one command.
╭─ Upload ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --name -n NAME Name for your uploaded policy. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * --policy -p POLICY Policy specification: URI (bundle dir or .zip) or NAME or │ │ class=NAME[,data=FILE][,kw.x=val]. │ │ [required] │ │ --init-kwarg -k KEY=VAL Policy init kwargs (can be repeated). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Files ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --include-files -f PATH Files or directories to include (can be repeated). │ │ --setup-script PATH Python setup script to run before loading the policy. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tournament ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --season SEASON Tournament season (default: server's default season). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Validation ────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --dry-run Run the Docker smoke test only without uploading. │ │ --skip-validation Skip the Docker smoke test. │ │ --image TEXT Docker image for container validation. │ │ [default: ghcr.io/metta-ai/episode-runner:latest] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames ship -p ./submission.zip -n my-policy --season beta-cvc Ship a prepared submission bundle cogames ship -p ./submission.zip -n my-policy --dry-run Validate a prepared submission bundle locally
Usage: cogames auth login [OPTIONS]
Log in to CoGames.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --no-browser Skip opening browser automatically. │ │ --force -f Re-authenticate even if already logged in │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames auth logout [OPTIONS]
Log out of CoGames.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames auth get-login-url [OPTIONS]
Print the CoGames login URL.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames auth status [OPTIONS]
Show CoGames authentication status.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --server -s URL API server URL for /whoami verification. │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames auth get-token [OPTIONS]
Print the saved CoGames token.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames auth set-token [OPTIONS] TOKEN
Save a CoGames token.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * token TEXT Bearer token to save [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL [default: https://softmax.com/api] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season list [OPTIONS]
List tournament seasons.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season show [OPTIONS] SEASON
Show details for a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season versions [OPTIONS] SEASON
List versions of a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season stages [OPTIONS] SEASON
Show stages for a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season progress [OPTIONS] SEASON
Show season progress summary.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season leaderboard [OPTIONS] SEASON
Show season leaderboard.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ season_name SEASON Season name (default: server default). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --pool -p TEXT Pool name for stage-specific leaderboard. │ │ --type -t [policy|team|score-policies] Leaderboard type (policy, team, score-policies). │ │ [default: policy] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season teams [OPTIONS] SEASON
Show teams in a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season matches [OPTIONS] SEASON
Show matches in a season.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --limit -n INTEGER Number of matches to show. [default: 20] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames season pool-config [OPTIONS] SEASON POOL
Show configuration for a season pool.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * season_name SEASON Season name. [required] │ │ * pool_name POOL Pool name. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames episode list [OPTIONS]
List game episodes.
╭─ Filter ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY_VERSION_ID Filter by policy version ID. │ │ --tags -t TAGS Comma-separated key:value tag filters. │ │ --limit -n N Number of episodes to show. [default: 20] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON instead of table. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames episode show [OPTIONS] EPISODE_ID
Show details for a specific episode.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * episode_id TEXT Episode ID to show. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON instead of table. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames episode replay [OPTIONS] EPISODE_ID
Download and replay a game episode in MettaScope or the BitWorld global client.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * episode_id TEXT Episode ID to replay. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --output -o FILE Save replay to file instead of launching viewer. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --server URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames assay status [OPTIONS] POLICY_OR_RUN_ID
Show status of an assay run or the latest run for a policy.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * policy_or_run_id TEXT Assay run UUID, or policy name (name[:version]). [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames assay list [OPTIONS]
List assay runs.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p TEXT Filter by policy name[:version] or UUID. │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames assay results [OPTIONS] POLICY_OR_RUN_ID
Get scoring results for an assay run.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * policy_or_run_id TEXT Assay run UUID, or policy name (name[:version]). [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames assay submit [OPTIONS] POLICY
Submit an assay run for a policy.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * policy TEXT Policy name[:version] or UUID. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --source TEXT cogames mission set name to run (cvc_evals, role_specific_evals, …). │ │ [default: cvc_evals] │ │ --name -n TEXT Optional label for this assay run (used for deduplication). │ │ --compat-version -c TEXT Compat version override. │ │ --episodes -e INTEGER Episodes per mission. [default: 3] │ │ --max-steps INTEGER Max steps per episode. [default: 10000] │ │ --watch -w Poll until the run completes. │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Server ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --login-server URL Authentication server URL. [default: https://softmax.com/api] │ │ --server -s URL Tournament server URL. [default: https://api.observatory.softmax-research.net] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --json Print raw JSON. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames tutorial play [OPTIONS]
Interactive tutorial - learn to play Cogs vs Clips.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames tutorial cvc [OPTIONS]
Interactive CvC tutorial - learn roles and territory control.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames tutorial make-policy [OPTIONS]
Create a new policy from a template. Requires exactly one policy type.
╭─ Policy Type ───────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --trainable Create a trainable (neural network) policy. │ │ --scripted Create a scripted (rule-based) policy. │ │ --amongthem Create an AmongThem BitWorld scripted practice policy. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --output -o FILE Output file path. [default: my_policy.py] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames tutorial make-policy --trainable -o my_nn_policy.py Trainable (neural network) cogames tutorial make-policy --scripted -o my_scripted_policy.py Scripted (rule-based) cogames tutorial make-policy --amongthem -o amongthem_policy.py AmongThem scripted practice
Usage: cogames tutorial train [OPTIONS]
Train a policy on one or more missions. Requires the ``neural`` extra (PyTorch + PufferLib). Install with: ``pip install cogames[neural]``. By default, our 'lstm' policy architecture is used. You can select a different architecture (like 'stateless' or 'baseline'), or define your own implementing the MultiAgentPolicy interface with a trainable network() method (see mettagrid/policy/policy.py). Continue training from a checkpoint using URI format, or load weights into an explicit class with class=...,data=... syntax. Supply repeated -m flags to create a training curriculum that rotates through missions. Use wildcards (*) in mission names to match multiple missions at once.
╭─ Mission Setup ─────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --mission -m MISSION Missions to train on (wildcards supported, repeatable for curriculum). │ │ --cogs -c N Number of cogs (agents). [default: (from mission)] │ │ --variant -v VARIANT Mission variant (repeatable). │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Policy ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --policy -p POLICY Policy to train (URI (bundle dir or .zip) or NAME or │ │ class=NAME[,data=FILE][,kw.x=val]). │ │ [default: class=lstm] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Training ──────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --steps N [x>=1] Number of training steps. [default: 10000000000] │ │ --minibatch-size N [x>=1] Minibatch size for training. [default: 4096] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Hardware ──────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --device DEVICE Device to train on (auto, cpu, cuda, mps). [default: auto] │ │ --num-workers N [x>=1] Number of worker processes. [default: (CPU cores)] │ │ --parallel-envs N [x>=1] Number of parallel environments. │ │ --vector-batch-size N [x>=1] Vectorized environment batch size. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Reproducibility ───────────────────────────────────────────────────────────────────────────────────────────────╮ │ --seed N [x>=0] Seed for training RNG. [default: 42] │ │ --map-seed N [x>=0] MapGen seed for procedural map layout. [default: (same as --seed)] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Output ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --checkpoints DIR Path to save training checkpoints. [default: ./train_dir] │ │ --log-outputs Log training outputs. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Other ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples: cogames tutorial train -m arena Basic training cogames tutorial train -m arena -p class=baseline Train baseline policy cogames tutorial train -p ./train_dir/my_run:v5 Continue from checkpoint cogames tutorial train -p class=lstm,data=./weights.safetensors Load weights into class cogames tutorial train -m mission_1 -m mission_2 Curriculum (rotates) Wildcard patterns: cogames tutorial train -m 'machina_2_bigger:*' All missions on machina_2_bigger cogames tutorial train -m '*:shaped' All "shaped" missions cogames tutorial train -m 'machina*:shaped' All "shaped" on machina maps
Usage: cogames bitworld games [OPTIONS]
List installed BitWorld games.
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames bitworld quick-run [OPTIONS] GAME [PORT]
Compile and run a BitWorld game with local player clients.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * game TEXT BitWorld game folder name. [required] │ │ port [PORT] Port to bind. If omitted, BitWorld chooses one. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --players INTEGER RANGE [x>=1] Number of local player clients. [default: 1] │ │ --address TEXT Server bind address. [default: 127.0.0.1] │ │ --save-replay PATH Path for BitWorld replay output. │ │ --nim TEXT Nim compiler executable. [default: nim] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: cogames bitworld replay [OPTIONS] REPLAY_PATH
Replay a BitWorld recording in the global web viewer.
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * replay_path PATH BitWorld replay file. [required] │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --game TEXT BitWorld game folder override. Defaults to the replay header game. │ │ --port INTEGER Port to bind. If omitted, one is chosen. │ │ --address TEXT Server bind address. [default: 127.0.0.1] │ │ --browser-address TEXT Address the browser should use to reach the replay server. │ │ [default: 127.0.0.1] │ │ --duration FLOAT Seconds to keep the replay server alive. If omitted, wait until interrupted. │ │ --nim TEXT Nim compiler executable. [default: nim] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
If you use CoGames in your research, please cite:
@software{cogames2025,
title={CoGames: Multi-Agent Cooperative Game Environments},
author={Softmax},
year={2025},
url={https://github.com/Metta-AI/cogames}
}