The cambc CLI is your main tool for local development, testing, and interacting with the platform. Install it with pip install cambc.
Project setup
cambc starter
Scaffold a new Cambridge Battlecode project. Run this first after installing.
Creates the following project structure:
your-project/
├── cambc.toml # Project configuration
├── .gitignore # Ignores replays, __pycache__, venvs
├── bots/
│ └── starter/
│ └── main.py # Starter bot (optional, prompted)
└── maps/ # Custom maps (optional, prompted)
cambc.toml
The config file created by cambc starter. All fields have defaults and all CLI options override config values.
bots_dir = "bots" # Where to find bots
maps_dir = "maps" # Where to find maps
replay = "replay.replay26" # Default replay output path
seed = 1 # Default map seed
cambc run are resolved by first checking the raw path, then checking inside bots_dir. So cambc run starter opponent resolves to bots/starter and bots/opponent.
Local development
cambc run
Run a local match between two bots. No time limits are enforced locally.
cambc run <bot_a> <bot_b> [map]
| Argument | Description |
|---|
bot_a | First bot — a directory containing main.py, a .py file, or a name in bots_dir |
bot_b | Second bot — same formats as bot_a |
map | Optional .map26 map file. If omitted, uses the first map in maps_dir |
| Option | Description |
|---|
--replay PATH | Output replay file path (overrides cambc.toml default) |
--seed N | Map seed (overrides cambc.toml default) |
--watch | Open the visualiser automatically after the match |
cambc run starter starter # bot vs itself
cambc run my_bot opponent --seed 42 # fixed seed
cambc run my_bot opponent maps/custom.map26 # custom map
cambc run --watch my_bot opponent # run + auto-open visualiser
cambc run my_bot opponent --replay out.replay26 # custom replay path
cambc watch
View a replay in the browser-based visualiser.
cambc watch [replay_file]
cambc watch --match <match_id> [--game <n>]
localhost and opens your browser. Press Ctrl+C to stop the server.
cambc watch replay.replay26
cambc watch --match abc123 # opens match on platform
cambc watch --match abc123 --game 3 # specific game within the match
cambc map-editor
Open the map editor to create custom .map26 files.
cambc map-editor # local map editor
cambc map-editor --platform # open map editor on the platform
cambc login.
cambc login
Authenticate with the platform. Opens a browser window for OAuth login and stores your session locally.
The session persists across CLI invocations until it expires or you run cambc logout.
cambc logout
Clear stored credentials.
cambc submit
Upload a bot to compete on the ladder.
The path can be a directory containing main.py, a single .py file, or a .zip. Directories are auto-zipped before upload. See submission requirements for constraints.
cambc submit ./my_bot/ # directory (auto-zipped)
cambc submit my_bot.py # single file
cambc submit my_bot.zip # pre-zipped
cambc status
Show your current team, rating, rank, and member list.
Displays your username, team name, category, Glicko-2 rating with uncertainty, matches played, and team members with roles.
cambc unrated
Challenge another team to an unrated match using both teams’ latest submissions.
cambc unrated <opponent_team_id>
cambc unrated <opponent_team_id> --match <source_match_id>
| Option | Description |
|---|
--match ID | Use the opponent’s submission version from a specific past match instead of their latest |
Rate limits apply: max 10 test/unrated matches per 5 minutes, plus a 5-minute cooldown per matchup.
cambc test-run
Upload two local bots and run a remote match with full time limit enforcement on AWS Graviton3 hardware.
cambc test-run <bot_a> <bot_b> [map]
cambc run, this enforces the 2ms CPU time limit per round — use this to check your bot’s performance before submitting.
cambc test-run my_bot opponent # test two bots remotely
cambc test-run my_bot opponent maps/custom.map26 # with a custom map
cambc matches
View recent match history.
| Option | Description |
|---|
--type {ladder|unrated} | Filter by match type |
--team NAME | Filter by team name (substring match) |
--limit N | Number of matches to show (default 20, max 100) |
--cursor CURSOR | Pagination cursor from previous results |
cambc match
View details of a specific match including per-game results.
Shows match status, teams, score, rating delta, timestamps, and a table of individual games with map, winner, win condition, and turns played.
cambc test-matches
View your remote test run history.
cambc test-matches [--limit N]
cambc teams
Search for teams or view team details.
cambc teams search <query> # search by name
cambc teams info <team_id> # view team details
