CLI reference - Cambridge Battlecode

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.

cambc starter

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)

The starter bot demonstrates core gameplay: the core spawns builder bots, builders explore by laying roads, and when they find ore they build harvesters on it.

`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

Bot paths in 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]

Arguments:

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`

Options:

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
`--tle N`	Turn time limit in milliseconds (0 to disable, server uses 2)
`--map-random`	Pick a random map from the maps directory instead of the first one

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

After the match completes, cambc run prints a summary showing the winner, win condition, turn count, and a resource breakdown (titanium, axionite, units, and buildings) for each team.

`cambc watch`

View a replay in the browser-based visualiser.

cambc watch [replay_file]
cambc watch --match <match_id> [--game <n>]

Local replay: Serves the visualiser on localhost and opens your browser. Press Ctrl+C to stop the server.

cambc watch replay.replay26

Platform match: Opens the platform visualiser in your browser for a specific match.

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

Platform commands

These commands interact with the online platform at game.battlecode.cam. Most require authentication via cambc login. Authenticate with the platform. Opens a browser window for OAuth login and stores your session locally.

cambc login

The session persists across CLI invocations until it expires or you run cambc logout.

`cambc logout`

Clear stored credentials.

cambc logout

`cambc submit`

Upload a bot to compete on the ladder.

cambc submit <path>

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.

cambc status

Displays your username, team name, category, Elo rating, matches played, and team members with roles.

`cambc match`

The cambc match group provides all match-related commands. When called with just a match ID, it defaults to showing match details.

`cambc match info`

View details of a specific match including per-game results.

cambc match info <match_id>
cambc match <match_id>          # shorthand — defaults to info

Shows match status, teams, score, rating delta, timestamps, and a table of individual games with map, winner, win condition, and turns played.

`cambc match list`

View recent match history.

cambc match list [options]

Option	Description
`--type {ladder\|unrated}`	Filter by match type
`--team NAME`	Filter by team name or ID
`--mine`	Show only your team’s matches
`--limit N`	Number of matches to show (default 20, max 100)
`--cursor CURSOR`	Pagination cursor from previous results

`cambc match unrated`

Challenge another team to an unrated match.

cambc match unrated <opponent_team_id>
cambc match unrated <opponent_team_id> --match <source_match_id>
cambc match unrated <opponent_team_id> --map arena --map galaxy

Option	Description
`--match ID`	Use the opponent’s submission version from a specific past match instead of their latest
`--map NAME`	Map name (repeatable, up to 5). If omitted, 5 random maps are used

Unrated matches run on the same AWS infrastructure as ladder matches with full time limit enforcement but do not affect ratings. They are prioritised over ladder matches for faster results.

Rate limits apply: max 10 test/unrated matches per 10 minutes.

`cambc match test`

Upload two local bots and run a remote match with full time limit enforcement on AWS Graviton3 hardware.

cambc match test <bot_a> <bot_b> [maps...]

Both bots are packaged and uploaded to the server. Unlike cambc run, this enforces the 2ms CPU time limit per round — use this to check your bot’s performance before submitting. You can optionally specify .map26 files — one per game.

cambc match test my_bot opponent                           # test two bots remotely
cambc match test my_bot opponent maps/arena.map26          # with a specific map

`cambc match replay`

Download replay files for a completed match.

cambc match replay <match_id>              # download all 5 game replays
cambc match replay <match_id> --game 3     # download a specific game
cambc match replay <match_id> -o out.replay26  # custom output path

`cambc match watch`

Open a match replay in the browser.

cambc match watch <match_id>
cambc match watch <match_id> --game 3

`cambc match tests`

View your team’s remote test run history.

cambc match tests [--limit N]

`cambc team`

Search for teams or view team details.

cambc team search <query>     # search by name
cambc team info <team_id>     # view team details

​Project setup

​cambc starter

​cambc.toml

​Local development

​cambc run

​cambc watch

​cambc map-editor

​Platform commands

​cambc login

​cambc logout

​cambc submit

​cambc status

​cambc match

​cambc match info

​cambc match list

​cambc match unrated

​cambc match test

​cambc match replay

​cambc match watch

​cambc match tests

​cambc team

Project setup

`cambc starter`

`cambc.toml`

Local development

`cambc run`

`cambc watch`

`cambc map-editor`

Platform commands

`cambc login`

`cambc logout`

`cambc submit`

`cambc status`

`cambc match`

`cambc match info`

`cambc match list`

`cambc match unrated`

`cambc match test`

`cambc match replay`

`cambc match watch`

`cambc match tests`

`cambc team`