Change cli to typer interface

Author: john-b-yang

CONTRIBUTING.md

@@ -101,13 +101,13 @@ CodeClash/
 │   ├── agents/          # AI agent implementations (MiniSWEAgent, etc.)
 │   ├── arenas/          # Game arena implementations
 │   ├── analysis/        # Post-tournament analysis tools
+|   ├── cli/             # CLI entrypoint
 │   ├── tournaments/     # Tournament orchestration
 │   ├── viewer/          # Web-based results viewer
 │   └── utils/           # Shared utilities
 ├── configs/             # Tournament configuration files
 ├── docs/                # Documentation (MkDocs)
-├── tests/               # Test suite
-└── main.py              # Main entry point
+└──  tests/               # Test suite
 ```
 
 ## Types of Contributions
@@ -170,7 +170,7 @@ Analysis tools live in `codeclash/analysis/`. We're particularly interested in:
 | Preview docs | `uv run mkdocs serve` |
 | Build wheel | `uv build --wheel` |
 | Build wheel + sdist | `uv build` |
-| Run a tournament | `uv run python main.py <config>` |
+| Run a tournament | `uv run codeclash run <config>` |
 | View results | `uv run python scripts/run_viewer.py` |
 
 ### Building Distributions

README.md

@@ -54,7 +54,7 @@ uv sync --extra dev
 cp .env.example .env  # Then edit .env with your GITHUB_TOKEN
 
 # Run a test battle
-uv run python main.py configs/test/battlesnake.yaml
+uv run codeclash run configs/test/battlesnake.yaml
 ```
 
 > [!TIP]
@@ -66,14 +66,14 @@ uv run python main.py configs/test/battlesnake.yaml
 
 ```bash
 pip install -e '.[dev]'
-python main.py configs/test/battlesnake.yaml
+codeclash run configs/test/battlesnake.yaml
 ```
 </details>
 
 Once this works, you should be set up to run a real tournament!
 To run *Claude Sonnet 4.5* against *o3* in a *BattleSnake* tournament with *5 rounds* and *1000 competition simulations* per round, run:
 ```bash
-uv run python main.py configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
+uv run codeclash run configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
 ```
 
 ## ⚔️ How It Works

codeclash/arenas/bomberland/runtime/README.md

@@ -27,7 +27,7 @@ Round simulation counts must be even so each player receives both starting sides
 Smoke command from the repository root:
 
 ```bash
-uv run python main.py configs/examples/Bomberland__dummy__r1__s2.yaml -o /tmp/codeclash-bomberland-smoke
+uv run codeclash run configs/examples/Bomberland__dummy__r1__s2.yaml -o /tmp/codeclash-bomberland-smoke
 ```
 
 Use a fresh `-o` directory when rerunning the smoke check. Expected output:

codeclash/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CodeClash command-line interface (`codeclash ...`)."""
+
+from codeclash.cli.app import app
+
+__all__ = ["app"]

main.py codeclash/cli/app.pymain.py renamed to codeclash/cli/app.py

@@ -1,35 +1,60 @@
-import argparse
+"""Root `codeclash` Typer app.
+
+Single entrypoint for CodeClash. Subcommands:
+    codeclash run <config>            run a PvP tournament
+    codeclash ladder make <config>    build a ladder (round-robin ranking)
+    codeclash ladder run <config>     send a model up a ranked ladder
+    codeclash rank {win-rate,elo,matrix} ...   compute standings from logs
+"""
+
 import getpass
 import random
 import time
 import uuid
 from pathlib import Path
+from typing import Optional
 
+import typer
 import yaml
 
 from codeclash import CONFIG_DIR
+from codeclash.cli.ladder import ladder_app
+from codeclash.cli.rank import rank_app
 from codeclash.constants import LOCAL_LOG_DIR
 from codeclash.tournaments.pvp import PvpTournament
 from codeclash.utils.aws import is_running_in_aws_batch
 from codeclash.utils.yaml_utils import resolve_includes
 
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="CodeClash: run coding-game tournaments, build ladders, and rank players.",
+)
+app.add_typer(ladder_app, name="ladder", help="Build and run CC:Ladder tournaments.")
+app.add_typer(rank_app, name="rank", help="Compute player standings from game logs.")
 
-def main(
-    config_path: Path,
-    *,
-    cleanup: bool = False,
-    output_dir: Path | None = None,
-    suffix: str = "",
-    keep_containers: bool = False,
+
+@app.command()
+def run(
+    config_path: Path = typer.Argument(..., help="Path to the tournament config file."),
+    cleanup: bool = typer.Option(False, "--cleanup", "-c", help="Clean up the game environment after running."),
+    output_dir: Optional[Path] = typer.Option(
+        None, "--output-dir", "-o", help="Output directory (default: logs/<user>)."
+    ),
+    suffix: str = typer.Option("", "--suffix", "-s", help="Suffix for the output folder name (no leading dot)."),
+    keep_containers: bool = typer.Option(
+        False, "--keep-containers", "-k", help="Do not remove containers after games/agent finish."
+    ),
 ):
+    """Run a PvP tournament from a config file."""
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
     config = yaml.safe_load(preprocessed_yaml)
 
     def get_output_path() -> Path:
         if is_running_in_aws_batch():
             # Offset timestamp by random seconds to avoid collisions
-            # Hopefully that means we can just remove the uuid part later on
             offset = random.randint(0, 600)
             timestamp = time.strftime("%y%m%d%H%M%S", time.localtime(time.time() + offset))
         else:
@@ -48,7 +73,6 @@ def get_output_path() -> Path:
         if transparent:
             folder_name += ".transparent"
         if is_running_in_aws_batch():
-            # Also add a UUID just to be safe
             _uuid = str(uuid.uuid4())
             folder_name += f".{_uuid}-uuid"
         if output_dir is None:
@@ -60,46 +84,14 @@ def get_output_path() -> Path:
             return output_dir / folder_name
 
     full_output_dir = get_output_path()
-
     tournament = PvpTournament(config, output_dir=full_output_dir, cleanup=cleanup, keep_containers=keep_containers)
     tournament.run()
 
 
-def main_cli(argv: list[str] | None = None):
-    parser = argparse.ArgumentParser(description="CodeClash")
-    parser.add_argument(
-        "config_path",
-        type=Path,
-        help="Path to the config file.",
-    )
-    parser.add_argument(
-        "-c",
-        "--cleanup",
-        action="store_true",
-        help="If set, do not clean up the game environment after running.",
-    )
-    parser.add_argument(
-        "-o",
-        "--output-dir",
-        type=Path,
-        help="Sets the output directory (default is 'logs' with current user subdirectory).",
-    )
-    parser.add_argument(
-        "-s",
-        "--suffix",
-        type=str,
-        help="Suffix to attach to the folder name. Does not include leading dot or underscore.",
-        default="",
-    )
-    parser.add_argument(
-        "-k",
-        "--keep-containers",
-        action="store_true",
-        help="Do not remove containers after games/agent finish",
-    )
-    args = parser.parse_args(argv)
-    main(**vars(args))
+def main() -> None:
+    """Console-script entrypoint (`codeclash`)."""
+    app()
 
 
 if __name__ == "__main__":
-    main_cli()
+    app()

scripts/run_ladder.py codeclash/cli/ladder.pyscripts/run_ladder.py renamed to codeclash/cli/ladder.py

@@ -1,24 +1,67 @@
-import argparse
+"""`codeclash ladder` subcommands: build a ladder (make) and climb it (run)."""
+
 import getpass
 import time
 from pathlib import Path
+from typing import Optional
 
+import typer
 import yaml
 
 from codeclash import CONFIG_DIR
 from codeclash.constants import LOCAL_LOG_DIR
 from codeclash.tournaments.pvp import PvpTournament
 from codeclash.utils.yaml_utils import resolve_includes
 
+ladder_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, context_settings={"help_option_names": ["-h", "--help"]}
+)
+
+
+@ladder_app.command("make")
+def make(
+    config_path: Path = typer.Argument(..., help="Path to the ladder (round-robin) config file."),
+):
+    """Build a ladder: run PvP tournaments across all pairs of players (for ranking)."""
+    yaml_content = config_path.read_text()
+    preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
+    config = yaml.safe_load(preprocessed_yaml)
 
-def main(
-    config_path: Path,
-    *,
-    cleanup: bool = False,
-    output_dir: Path | None = None,
-    suffix: str = "",
-    keep_containers: bool = False,
+    players = config["players"]
+    num_players = len(players)
+    for i in range(num_players):
+        for j in range(i + 1, num_players):
+            player1 = players[i]
+            player1["name"] = player1["branch_init"]
+            player2 = players[j]
+            player2["name"] = player2["branch_init"]
+            pvp_config = {
+                **config,
+                "players": [player1, player2],
+            }
+
+            vs = f"PvpTournament.{player1['name']}_vs_{player2['name']}".replace("/", "_")
+            output_dir = LOCAL_LOG_DIR / "ladder" / config["game"]["name"] / vs
+            try:
+                tournament = PvpTournament(pvp_config, output_dir=output_dir)
+            except FileExistsError:
+                continue
+            tournament.run()
+
+
+@ladder_app.command("run")
+def run(
+    config_path: Path = typer.Argument(..., help="Path to the ladder config (with `player` + `ladder`)."),
+    cleanup: bool = typer.Option(False, "--cleanup", "-c", help="Clean up the game environment after running."),
+    output_dir: Optional[Path] = typer.Option(
+        None, "--output-dir", "-o", help="Output directory (default: logs/<user>)."
+    ),
+    suffix: str = typer.Option("", "--suffix", "-s", help="Suffix for the output folder name (no leading dot)."),
+    keep_containers: bool = typer.Option(
+        False, "--keep-containers", "-k", help="Do not remove containers after games/agent finish."
+    ),
 ):
+    """Send a model up a ranked ladder, rung by rung, until it loses."""
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)
     config = yaml.safe_load(preprocessed_yaml)
@@ -88,43 +131,3 @@ def main(
 
     print(f"Ladder tournament complete. Logs saved to {parent_dir}")
     print(f"Final opponent faced: {opponent['name']} (rank {opponent_rank}/{len(ladder)} in ladder)")
-
-
-def main_cli(argv: list[str] | None = None):
-    parser = argparse.ArgumentParser(description="CodeClash")
-    parser.add_argument(
-        "config_path",
-        type=Path,
-        help="Path to the config file.",
-    )
-    parser.add_argument(
-        "-c",
-        "--cleanup",
-        action="store_true",
-        help="If set, do not clean up the game environment after running.",
-    )
-    parser.add_argument(
-        "-o",
-        "--output-dir",
-        type=Path,
-        help="Sets the output directory (default is 'logs' with current user subdirectory).",
-    )
-    parser.add_argument(
-        "-s",
-        "--suffix",
-        type=str,
-        help="Suffix to attach to the folder name. Does not include leading dot or underscore.",
-        default="",
-    )
-    parser.add_argument(
-        "-k",
-        "--keep-containers",
-        action="store_true",
-        help="Do not remove containers after games/agent finish",
-    )
-    args = parser.parse_args(argv)
-    main(**vars(args))
-
-
-if __name__ == "__main__":
-    main_cli()

codeclash/cli/rank.py

@@ -0,0 +1,46 @@
+"""`codeclash rank` subcommands: compute player standings from game logs."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from codeclash.analysis import matrix as matrix_mod
+from codeclash.analysis.metrics import win_rate as win_rate_mod
+from codeclash.constants import LOCAL_LOG_DIR
+
+rank_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, context_settings={"help_option_names": ["-h", "--help"]}
+)
+
+
+@rank_app.command("win-rate")
+def win_rate(
+    logs: Path = typer.Argument(LOCAL_LOG_DIR, help="Path to game logs (default: logs/)."),
+):
+    """Print per-game and game-agnostic win rates for each model."""
+    win_rate_mod.main(logs)
+
+
+@rank_app.command("matrix")
+def matrix(
+    pvp_output_dir: Path = typer.Argument(..., help="Path to a PvP tournament output directory."),
+    repetitions: int = typer.Option(3, "--repetitions", "-n", help="Repetitions per matchup."),
+    max_workers: int = typer.Option(4, "--max-workers", "-w", help="Number of parallel game workers."),
+):
+    """Evaluate PvP tournament matrices (head-to-head win matrix)."""
+    matrix_mod.main(pvp_output_dir, n_repetitions=repetitions, max_workers=max_workers)
+
+
+@rank_app.command(
+    "elo",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+    help=(
+        "Fit a Bradley-Terry/Elo model and generate plots. Forwards all arguments to the elo "
+        "analysis module, e.g.:  codeclash rank elo -d logs/ --print-matrix --output-dir assets/elo_plots"
+    ),
+)
+def elo(ctx: typer.Context):
+    """Passthrough to `python -m codeclash.analysis.metrics.elo` (rich analysis + plots)."""
+    raise SystemExit(subprocess.run([sys.executable, "-m", "codeclash.analysis.metrics.elo", *ctx.args]).returncode)

codeclash/viewer/static/js/picker.js

@@ -503,7 +503,7 @@ async function fillTextareaWithAWSSubmitCommands() {
     // Format output as AWS submit commands
     const commands = successfulResults.map(
       (result) =>
-        `aws/run_job.py -- aws/docker_and_sync.sh python main.py configs/main/${result.config_name}`,
+        `aws/run_job.py -- aws/docker_and_sync.sh codeclash run configs/main/${result.config_name}`,
     );
     textarea.value = commands.join("\n");
 

configs/ablations/ladder/README.md

@@ -5,7 +5,7 @@ For a more static and hill-climb-able version of CodeClash, we introduce CC:Ladd
 For instance, for RobotRumble, we created a ladder by doing the following steps:
 1. From the online [leaderboard](https://robotrumble.org/boards/2), we manually crawled all open source, published bots and pushed them as branches to the [CC:RobotRumble](https://github.com/CodeClash-ai/RobotRumble) repository.
 2. We then created the `robotrumble.yaml` file in this folder.
-3. Next, from the repository root, we run `uv run python scripts/run_ladder.py configs/ablations/ladder/robotrumble.yaml`, which runs PvP Tournaments against all pairs of branches.
+3. Next, from the repository root, we run `uv run codeclash ladder run configs/ablations/ladder/robotrumble.yaml`, which runs PvP Tournaments against all pairs of branches.
 4. From these logs, we then calculate win rate to rank all models.
 
 You can follow these steps to create your own "CC:<arena>" ladder.

configs/ablations/ladder/make_battlesnake.yaml

@@ -1,5 +1,5 @@
 # Round-robin over ALL imported human BattleSnakes, used to RANK them (skill Phase 3).
-# Run:  uv run python scripts/make_ladder.py configs/ablations/ladder/make_battlesnake.yaml
+# Run:  uv run codeclash ladder make configs/ablations/ladder/make_battlesnake.yaml
 # Then rank from the logs with codeclash/analysis/metrics/win_rate.py (or elo.py).
 #
 # Params: args match the main BattleSnake configs (11x11, browser off). Following the