> ## Documentation Index
> Fetch the complete documentation index at: https://docs.battlecode.cam/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every command available in the cambc CLI.

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.

```bash theme={"dark"}
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.

```toml theme={"dark"}
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.

```bash theme={"dark"}
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 |

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
cambc watch replay.replay26
```

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

```bash theme={"dark"}
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.

```bash theme={"dark"}
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](https://game.battlecode.cam). Most require authentication via `cambc login`.

### `cambc login`

Authenticate with the platform. Opens a browser window for OAuth login and stores your session locally.

```bash theme={"dark"}
cambc login
```

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

### `cambc logout`

Clear stored credentials.

```bash theme={"dark"}
cambc logout
```

### `cambc submit`

Upload a bot to compete on the ladder.

```bash theme={"dark"}
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](/getting-started/submitting#bot-requirements) for constraints.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

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

#### `cambc match test`

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

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
cambc match watch <match_id>
cambc match watch <match_id> --game 3
```

#### `cambc match tests`

View your team's remote test run history.

```bash theme={"dark"}
cambc match tests [--limit N]
```

### `cambc team`

Search for teams or view team details.

```bash theme={"dark"}
cambc team search <query>     # search by name
cambc team info <team_id>     # view team details
```