### Start Balatrobot Server with Default Settings

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Launches the Balatrobot server using its default configuration. This is the most basic way to start the service.

```bash
# Start with default settings
uvx balatrobot serve
```

--------------------------------

### start

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Starts a new game run with a specified deck and stake.

```APIDOC
## start

### Description
Start a new game run.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **deck** (string) - Required - The type of deck to use (e.g., "RED").
- **stake** (string) - Required - The type of stake to use (e.g., "WHITE").

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "start",
  "params": {
    "deck": "RED",
    "stake": "WHITE"
  },
  "id": 1
}
```
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Standard commands to clone the BalatroBot repository and install project dependencies using make.

```bash
git clone https://github.com/your-repo/balatrobot.git
cd balatrobot
```

```bash
make install
```

--------------------------------

### Serve Balatro with Custom Installation Path

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Specifies a custom path to the Balatro executable. This is necessary if Balatro is not installed in the default location.

```bash
# Custom Balatro installation
uvx balatrobot serve --balatro-path /path/to/Balatro.exe
```

--------------------------------

### start

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Starts a new game run with a specified deck, stake, and optional seed.

```APIDOC
## start

### Description
Start a new game run.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version
- **method** (string) - Required - Method name, should be "start"
- **params** (object) - Required - Parameters for the method
  - **deck** (string) - Required - Deck to use
  - **stake** (string) - Required - Stake level
  - **seed** (string) - Optional - Seed for the run
- **id** (integer) - Required - Request ID

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "start",
  "params": {"deck": "BLUE", "stake": "WHITE", "seed": "TEST123"},
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC version
- **id** (integer) - Request ID
- **result** (object) - Result of the operation
  - **state** (string) - Current game state, will be `BLIND_SELECT`

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "BLIND_SELECT"
  }
}
```
```

--------------------------------

### Makefile Install Dependencies

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Install all project dependencies, including both development and testing groups.

```bash
make install
```

--------------------------------

### Start Balatro Server

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Use this command to start the Balatro server with the BalatroBot mod loaded and the API server running. Options can be configured via CLI flags or environment variables, with flags taking precedence.

```bash
uvx balatrobot serve [OPTIONS]
```

--------------------------------

### Installation and Server Launch

Source: https://context7.com/coder/balatrobot/llms.txt

Commands to install and launch Balatro with the BalatroBot mod and API server. Supports various configurations like fast mode, headless rendering, and custom ports.

```APIDOC
## Installation and Server Launch

**`uvx balatrobot serve`** — Start Balatro with the BalatroBot mod and API server.

Launches Balatro with the mod loaded and starts the JSON-RPC HTTP server. Auto-detects platform paths (Steam/macOS/Windows/Linux native). Supports fast mode, headless rendering, custom ports, and debug mode. All flags also readable from environment variables.

```bash
# Install and run in one step (no explicit install needed)
uvx balatrobot serve

# Fast headless mode for bots/CI
uvx balatrobot serve --fast --headless

# Render only when an API call arrives (useful for screenshots)
uvx balatrobot serve --fast --render-on-api

# Custom port with debug logging (requires DebugPlus mod)
uvx balatrobot serve --port 8080 --fast --debug

# Linux native (source code) platform
uvx balatrobot serve --platform native \
  --balatro-path /path/to/balatro/source \
  --love-path /usr/bin/love \
  --lovely-path /usr/local/lib/liblovely.so

# Configure via environment variables (useful in CI)
export BALATROBOT_PORT=8080
export BALATROBOT_FAST=1
export BALATROBOT_HEADLESS=1
uvx balatrobot serve

# Verify the server is up
curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"health","id":1}'
# → {"jsonrpc":"2.0","result":{"status":"ok"},"id":1}
```
```

--------------------------------

### Serve Command

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Starts Balatro with the BalatroBot mod loaded and the API server running. Options can be configured via CLI flags or environment variables.

```APIDOC
## serve Command

Start Balatro with the BalatroBot mod loaded and API server running.

```bash
uvx balatrobot serve [OPTIONS]
```

### Options

All options can be set via CLI flags or environment variables. CLI flags override environment variables.

| CLI Flag                        | Environment Variable             | Default       | Description                                |
| ------------------------------- | -------------------------------- | ------------- | ------------------------------------------ |
| `--host HOST`                   | `BALATROBOT_HOST`                | `127.0.0.1`   | Server hostname                            |
| `--port PORT`                   | `BALATROBOT_PORT`                | `12346`       | Server port                                |
| `--fast`                        | `BALATROBOT_FAST`                | `0`           | Enable fast mode (10x game speed)          |
| `--headless`                    | `BALATROBOT_HEADLESS`            | `0`           | Enable headless mode (minimal rendering)   |
| `--render-on-api`               | `BALATROBOT_RENDER_ON_API`       | `0`           | Render only on API calls                   |
| `--audio`                       | `BALATROBOT_AUDIO`               | `0`           | Enable audio                               |
| `--debug`                       | `BALATROBOT_DEBUG`               | `0`           | Enable debug mode (requires DebugPlus mod) |
| `--no-shaders`                  | `BALATROBOT_NO_SHADERS`          | `0`           | Disable all shaders                        |
| `--fps-cap FPS_CAP`             | `BALATROBOT_FPS_CAP`             | `60`          | Maximum FPS cap                            |
| `--gamespeed GAMESPEED`         | `BALATROBOT_GAMESPEED`           | `4`           | Game speed multiplier                      |
| `--animation-fps ANIMATION_FPS` | `BALATROBOT_ANIMATION_FPS`       | `10`          | Animation FPS                              |
| `--no-reduced-motion`           | `BALATROBOT_NO_REDUCED_MOTION`   | `0`           | Disable reduced motion                     |
| `--pixel-art-smoothing`         | `BALATROBOT_PIXEL_ART_SMOOTHING` | `0`           | Enable pixel art smoothing                 |
| `--balatro-path BALATRO_PATH`   | `BALATROBOT_BALATRO_PATH`        | auto-detected | Path to Balatro game directory             |
| `--lovely-path LOVELY_PATH`     | `BALATROBOT_LOVELY_PATH`         | auto-detected | Path to lovely library (dll/so/dylib)      |
| `--love-path LOVE_PATH`         | `BALATROBOT_LOVE_PATH`           | auto-detected | Path to LOVE executable (native only)      |
| `--platform PLATFORM`           | `BALATROBOT_PLATFORM`            | auto-detected | Platform: darwin, linux, windows, native   |
| `--logs-path LOGS_PATH`         | `BALATROBOT_LOGS_PATH`           | `logs`        | Directory for log files                    |
| `-h, --help`                    | -                                | -             | Show help message and exit                 |

!!! note "Mutually Exclusive Flags"

    `--headless` and `--render-on-api` are mutually exclusive.

**Note:** Boolean flags (`--fast`, `--headless`, etc.) use `1` for enabled and `0` for disabled when set via environment variables.
```

--------------------------------

### Launch BalatroBot Server for Development

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Starts the BalatroBot server with debug and fast mode enabled for development. Refer to the CLI Reference for more options.

```bash
balatrobot serve --debug --fast
```

--------------------------------

### start

Source: https://context7.com/coder/balatrobot/llms.txt

Starts a new Balatro run from the main menu. This method requires the game to be in the 'MENU' state and accepts parameters for deck, stake, and an optional seed. It returns the GameState object with the state set to 'BLIND_SELECT'.

```APIDOC
## `start` Method

**`start`** — Start a new Balatro run from the main menu.

Requires `MENU` state. Accepts a deck name, stake level, and optional seed string. Returns `GameState` with state `BLIND_SELECT`. All 15 decks and 8 stakes are supported.

```bash
# Start with Blue Deck on White Stake, seeded for reproducibility
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ 
    "jsonrpc": "2.0",
    "method": "start",
    "params": {"deck": "BLUE", "stake": "WHITE", "seed": "MYBOT1"},
    "id": 1
  }'

# Start with Plasma Deck on Gold Stake (hardest, rental jokers)
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ 
    "jsonrpc": "2.0",
    "method": "start",
    "params": {"deck": "PLASMA", "stake": "GOLD"},
    "id": 2
  }'
# Decks: RED BLUE YELLOW GREEN BLACK MAGIC NEBULA GHOST ABANDONED
#        CHECKERED ZODIAC PAINTED ANAGLYPH PLASMA ERRATIC
# Stakes: WHITE RED GREEN BLACK BLUE PURPLE ORANGE GOLD
```
```

--------------------------------

### Start New Run API Request

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Initiate a new game run with specified deck and stake.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "start", "params": {"deck": "RED", "stake": "WHITE"}, "id": 1}'
```

--------------------------------

### Launch Balatro with BalatroBot Server

Source: https://context7.com/coder/balatrobot/llms.txt

Use `uvx balatrobot serve` to start Balatro with the mod and API server. Supports various flags for headless operation, custom ports, and platform-specific configurations. Environment variables can also be used for configuration.

```bash
# Install and run in one step (no explicit install needed)
uvx balatrobot serve

# Fast headless mode for bots/CI
uvx balatrobot serve --fast --headless

# Render only when an API call arrives (useful for screenshots)
uvx balatrobot serve --fast --render-on-api

# Custom port with debug logging (requires DebugPlus mod)
uvx balatrobot serve --port 8080 --fast --debug

# Linux native (source code) platform
uvx balatrobot serve --platform native \
  --balatro-path /path/to/balatro/source \
  --love-path /usr/bin/love \
  --lovely-path /usr/local/lib/liblovely.so

# Configure via environment variables (useful in CI)
export BALATROBOT_PORT=8080
export BALATROBOT_FAST=1
export BALATROBOT_HEADLESS=1
uvx balatrobot serve

# Verify the server is up
curl -X POST http://127.0.0.1:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"health","id":1}'
# → {"jsonrpc":"2.0","result":{"status":"ok"},"id":1}
```

--------------------------------

### Start Balatrobot Server in Fast Mode

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Starts the Balatrobot server in fast mode, which is optimized for development environments. This can speed up development cycles.

```bash
# Start with fast mode for development
uvx balatrobot serve --fast
```

--------------------------------

### Launch BalatroBot CLI

Source: https://github.com/coder/balatrobot/blob/main/docs/installation.md

Start the BalatroBot mod using the command-line interface. Ensure Balatro is running.

```bash
uvx balatrobot serve
```

--------------------------------

### Start New Game API Call

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Initiate a new game with specified deck and stake. Ensure the parameters are correctly formatted as a JSON string.

```bash
uvx balatrobot api start '{"deck": "RED", "stake": "WHITE"}'
```

--------------------------------

### Start Balatrobot Server in Debug Mode

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Enables debug mode for the Balatrobot server, which requires the DebugPlus mod to be installed. This is useful for in-depth debugging.

```bash
# Start with debug mode (requires DebugPlus mod)
uvx balatrobot serve --fast --debug
```

--------------------------------

### Start Balatrobot Server in Headless Mode

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Launches the Balatrobot server in headless mode, suitable for automated testing scenarios where no graphical interface is needed.

```bash
# Start headless for automated testing
uvx balatrobot serve --headless --fast
```

--------------------------------

### Start New Game Run

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Initiates a new game run with a specified deck, stake, and an optional seed. Requires the game to be in the MENU state.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "start", "params": {"deck": "BLUE", "stake": "WHITE", "seed": "TEST123"}, "id": 1}'
```

--------------------------------

### Run Integration Tests

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Execute integration tests that require starting a Balatro instance. These are marked with 'integration'.

```bash
pytest tests/lua -m integration
```

--------------------------------

### Create New Lua Endpoint

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Example structure for a new Lua endpoint. Define its name, description, schema, optional state requirements, and execution logic.

```lua
return {
  name = "your_endpoint",
  description = "Brief description",
  schema = {
    param_name = {
      type = "string",
      required = true,
      description = "Parameter description",
    },
  },
  requires_state = { G.STATES.SHOP },  -- Optional
  execute = function(args, send_response)
    -- Implementation
    send_response(BB_GAMESTATE.get_gamestate())
  end,
}
```

--------------------------------

### Configure Environment Variables with direnv

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

This example shows how to configure environment variables for BalatroBot development using a .envrc file. Ensure paths are updated for your system and never commit this file as it may contain secrets.

```bash
# Load the virtual environment
source .venv/bin/activate

# Python-specific variables
export PYTHONUNBUFFERED="1"
export PYTHONPATH="${PWD}/src:${PYTHONPATH}"
export PYTHONPATH="${PWD}/tests:${PYTHONPATH}"

# BALATROBOT env vars
export BALATROBOT_FAST=1
export BALATROBOT_DEBUG=1
export BALATROBOT_LOVE_PATH='/path/to/Balatro/love'
export BALATROBOT_LOVELY_PATH='/path/to/liblovely.dylib'
export BALATROBOT_RENDER_ON_API=0
export BALATROBOT_HEADLESS=1
export BALATROBOT_AUDIO=0
```

--------------------------------

### Run the Bot Script

Source: https://github.com/coder/balatrobot/blob/main/docs/example-bot.md

This command executes the Python bot script after the BalatroBot server has been started. The bot will then attempt to play a game of Balatro.

```bash
uv run bot.py
```

--------------------------------

### Start a New Balatro Run

Source: https://context7.com/coder/balatrobot/llms.txt

Initiates a new Balatro run from the main menu. Requires the `MENU` state and accepts parameters for deck, stake, and an optional seed. Returns the initial `GameState`.

```bash
# Start with Blue Deck on White Stake, seeded for reproducibility
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ 
    "jsonrpc": "2.0",
    "method": "start",
    "params": {"deck": "BLUE", "stake": "WHITE", "seed": "MYBOT1"},
    "id": 1
  }'
```

```bash
# Start with Plasma Deck on Gold Stake (hardest, rental jokers)
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ 
    "jsonrpc": "2.0",
    "method": "start",
    "params": {"deck": "PLASMA", "stake": "GOLD"},
    "id": 2
  }'
```

--------------------------------

### Launch Balatrobot on macOS with Custom Paths

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Launches the Balatrobot server on macOS, specifying custom paths for the LOVE runtime and the Lovely Injector dynamic library. This is useful for non-standard installations.

```bash
# Auto-detects paths
uvx balatrobot serve --fast

# Or specify custom paths
uvx balatrobot serve --love-path "/path/to/love" --lovely-path "/path/to/liblovely.dylib"
```

--------------------------------

### Launch Balatrobot on Windows with Custom Paths

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Launches the Balatrobot server on Windows, specifying custom paths for the Balatro executable and the Lovely Injector DLL. This is useful when auto-detection fails or custom installations are used.

```powershell
# Auto-detects paths
uvx balatrobot serve --fast

# Or specify custom paths
uvx balatrobot serve --love-path "C:\Custom\Path\Balatro.exe" --lovely-path "C:\Custom\Path\version.dll"
```

--------------------------------

### Capture Screenshot

Source: https://context7.com/coder/balatrobot/llms.txt

Captures a PNG screenshot of the current game window and saves it to the specified absolute path. Requires the server to be started with `--render-on-api` or without `--headless`.

```bash
# Start server with render-on-api for deterministic screenshots

```

--------------------------------

### Python: Use Consumables Needing No Targets

Source: https://context7.com/coder/balatrobot/llms.txt

Example using Python to iterate through consumables and use those that do not require target cards, such as Planet cards.

```python
state = client.call("gamestate")
for i, card in enumerate(state["consumables"]["cards"]):
    if card["set"] in ("PLANET",):   # Planet cards need no targets
        state = client.call("use", {"consumable": i})
        break
```

--------------------------------

### screenshot Method

Source: https://context7.com/coder/balatrobot/llms.txt

Captures a PNG screenshot of the current game window and saves it to a specified absolute path. This method requires the server to be started with the `--render-on-api` flag or without the `--headless` flag to produce a meaningful image.

```APIDOC
## `screenshot` Method

**`screenshot`** — Capture a PNG screenshot of the current game window.

Saves a PNG file at the given absolute path. Requires the server to be started with `--render-on-api` (or without `--headless`) to produce a meaningful image.

```bash
# Start server with render-on-api for deterministic screenshots

```

--------------------------------

### Basic Balatro Game Loop with API

Source: https://context7.com/coder/balatrobot/llms.txt

Demonstrates a typical game loop using the Balatro Bot API. Handles starting a seeded run, processing game states (BLIND_SELECT, SELECTING_HAND, ROUND_EVAL, SHOP), and managing game over conditions. Includes error handling for API and connection issues.

```python
try:
    # Return to menu first, then start a seeded run
    client.call("menu")
    state = client.call("start", {"deck": "RED", "stake": "WHITE", "seed": "BOT42"})
    print(f"Run started, seed={state['seed']}, state={state['state']}")

    while state["state"] != "GAME_OVER":
        match state["state"]:
            case "BLIND_SELECT":
                state = client.call("select")
            case "SELECTING_HAND":
                n = min(5, len(state["hand"]["cards"]))
                state = client.call("play", {"cards": list(range(n))})
            case "ROUND_EVAL":
                state = client.call("cash_out")
            case "SHOP":
                state = client.call("next_round")
            case _:
                state = client.call("gamestate")

    print("Won!" if state["won"] else f"Game over at ante {state['ante_num']}")

except APIError as e:
    # e.name  → "INVALID_STATE" / "BAD_REQUEST" / "NOT_ALLOWED" / "INTERNAL_ERROR"
    # e.code  → -32002 / -32001 / -32003 / -32000
    print(f"API error [{e.code}] {e.name}: {e.message}")

except httpx.ConnectError:
    print("Could not connect — is Balatro running with the mod loaded?")
```

--------------------------------

### Configure Lua Language Server

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

This JSON configuration sets up the Lua Language Server for IDE support, including autocomplete and diagnostics. Update the workspace library paths to match your local installations of Steamodded, Love2D, and LuaSocket.

```json
{
  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
  "workspace": {
    "library": [
      "/path/to/Balatro/Mods/smods/lsp_def",
      "/path/to/love2d/library",
      "/path/to/luasocket/library",
      "src/lua"
    ]
  },
  "diagnostics": {
    "disable": [
      "lowercase-global"
    ],
    "globals": [
      "G",
      "BB_GAMESTATE",
      "BB_ERROR_NAMES",
      "BB_ENDPOINTS"
    ]
  },
  "type": {
    "weakUnionCheck": true
  }
}
```

--------------------------------

### Makefile Generate Test Fixtures

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Generate necessary test fixtures. This command may start Balatro. Fixtures are auto-generated if missing during test runs.

```bash
make fixtures
```

--------------------------------

### Python: Play Highest Index Cards

Source: https://context7.com/coder/balatrobot/llms.txt

Example using Python to play the highest index cards from the hand. Fetches game state, determines the number of cards, and plays the last 5 cards.

```python
state = client.call("gamestate")
n = len(state["hand"]["cards"])
state = client.call("play", {"cards": list(range(max(0, n-5), n))})
print(f"Chips scored: {state['round']['chips']}, hands left: {state['round']['hands_left']}")
```

--------------------------------

### Makefile Help Command

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Display all available commands in the Makefile with their descriptions.

```bash
make help
```

--------------------------------

### Verify BalatroBot Installation

Source: https://github.com/coder/balatrobot/blob/main/docs/installation.md

Test the BalatroBot installation by sending a health check request to its API endpoint. This confirms the mod is running and accessible.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "health", "id": 1}'
```

--------------------------------

### Get Game State API Request

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Retrieve the complete current state of the game.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "gamestate", "id": 1}'
```

--------------------------------

### Buy Card, Voucher, or Pack from Shop

Source: https://context7.com/coder/balatrobot/llms.txt

Use the `buy` method in the `SHOP` state to purchase items. Specify `card`, `voucher`, or `pack` with their respective 0-based indices.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"buy","params":{"card":0},"id":1}'
```

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"buy","params":{"voucher":1},"id":1}'
```

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"buy","params":{"pack":0},"id":1}'
```

--------------------------------

### Launch Balatrobot on Native Linux Platform

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Launches the Balatrobot server on Linux using the native platform. This requires specifying paths to the Balatro source code and the LÖVE executable.

```bash
# Copy game settings to the expected location
mkdir -p ~/.local/share/love/balatro
cp -r /path/to/balatro/settings/* ~/.local/share/love/balatro/

# Launch with native platform
uvx balatrobot serve --platform native --balatro-path /path/to/balatro/source
```

--------------------------------

### Get Game State API Call

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Retrieve the current game state from the running BalatroBot server.

```bash
uvx balatrobot api gamestate
```

--------------------------------

### menu

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Returns the game to the main menu.

```APIDOC
## menu

### Description
Return to the main menu.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Request Body
```json
{
  "jsonrpc": "2.0",
  "method": "menu",
  "id": 1
}
```
```

--------------------------------

### Add Pack to Shop

Source: https://context7.com/coder/balatrobot/llms.txt

Adds a specified pack to the shop. This requires the game to be in the SHOP state. For example, adding a Mega Buffoon Pack.

```bash
# Add a Mega Buffoon Pack to the shop (requires SHOP state)
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"add","params":{"key":"p_buffoon_mega_1"},"id":1}'
```

--------------------------------

### menu

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Returns the game to the main menu from any current state.

```APIDOC
## menu

### Description
Return to the main menu from any state.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version
- **method** (string) - Required - Method name, should be "menu"
- **id** (integer) - Required - Request ID

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "menu",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC version
- **id** (integer) - Request ID
- **result** (object) - Result of the operation
  - **state** (string) - Current game state, will be `MENU`

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "MENU"
  }
}
```
```

--------------------------------

### Take a Screenshot

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Capture a screenshot of the current game state and save it to a specified file path.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "screenshot", "params": {"path": "/tmp/screenshot.png"}, "id": 1}'
```

--------------------------------

### Manual Launch for Development

Source: https://github.com/coder/balatrobot/blob/main/CLAUDE.md

Manually launch the BalatroBot CLI with specific flags for development or debugging purposes.

```bash
balatrobot --fast --debug
```

--------------------------------

### Create Symlink for Mods Folder

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Instructions for creating a symbolic link to the balatrobot project in the Balatro Mods folder for easier development on different operating systems.

```bash
ln -s "$(pwd)" ~/Library/Application\ Support/Balatro/Mods/balatrobot
```

```bash
ln -s "$(pwd)" ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/
```

```bash
ln -s "$(pwd)" ~/.config/love/Mods/balatrobot/
```

```powershell
New-Item -ItemType SymbolicLink -Path "$env:APPDATA\Balatro\Mods\balatrobot" -Target (Get-Location)
```

--------------------------------

### Get Game State (Python SDK)

Source: https://context7.com/coder/balatrobot/llms.txt

Retrieves the current game state, including hand, deck, and round information. This is a client-side SDK method.

```APIDOC
## client.call("gamestate") (Python SDK)

### Description
Retrieves the current game state. This method is part of the Python SDK and is used to inspect game data.

### Method
SDK Call

### Parameters
None

### Response Example (Conceptual)
```json
{
  "hand": {
    "cards": [...] 
  },
  "round": {
    "chips": 100,
    "hands_left": 3
  }
}
```
```

--------------------------------

### Add Joker with Modifiers

Source: https://context7.com/coder/balatrobot/llms.txt

Adds a joker to the game with specified modifiers like edition, seal, or enhancement. For example, adding a Polychrome Blueprint joker.

```bash
# Add a Polychrome Blueprint joker
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc":"2.0","method":"add", "params":{"key":"j_blueprint","edition":"POLYCHROME"}, "id":1 }'
```

--------------------------------

### Add Playing Card with Modifiers

Source: https://context7.com/coder/balatrobot/llms.txt

Adds a specific playing card with optional modifiers such as seal and enhancement. For example, an Ace of Spades with Gold Seal and Glass enhancement.

```bash
# Add an Ace of Spades with Gold Seal and Glass enhancement
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc":"2.0","method":"add", "params":{"key":"S_A","seal":"GOLD","enhancement":"GLASS"}, "id":1 }'
```

--------------------------------

### health

Source: https://context7.com/coder/balatrobot/llms.txt

Checks the health of the Balatro Bot's HTTP server. It returns a status of 'ok' if the server is accepting requests, making it useful as a readiness probe before starting a bot run.

```APIDOC
## `health` Method

**`health`** — Server health check with no required state.

Returns `{"status": "ok"}` whenever the mod's HTTP server is accepting requests. Use as a readiness probe before beginning a bot run.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"health","id":1}'
# → {"jsonrpc":"2.0","result":{"status":"ok"},"id":1}
```
```

--------------------------------

### rpc.discover Method

Source: https://context7.com/coder/balatrobot/llms.txt

Retrieves the full OpenRPC specification document for the Balatrobot API.

```APIDOC
## GET /rpc.discover

### Description
Retrieve the full OpenRPC specification document for all available methods, parameters, and response types.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method name, should be "rpc.discover".
- **id** (integer) - Required - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "rpc.discover",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **result** (object) - The OpenRPC specification document.
- **id** (integer) - The identifier for the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "methods": [
      {"name": "health"},
      {"name": "gamestate"},
      {"name": "start"},
      {"name": "select"},
      ...
    ]
  },
  "id": 1
}
```
```

--------------------------------

### save and load Methods

Source: https://context7.com/coder/balatrobot/llms.txt

Checkpoint and restore game state to and from a file. The `save` method writes the current run state to a specified file path, while the `load` method restores a previously saved run. This is useful for creating repeatable test scenarios or checkpointing before critical decisions.

```APIDOC
## `save` and `load` Methods

**`save` / `load`** — Checkpoint and restore game state to/from a file.

`save` writes the current run state to the specified file path; `load` restores a saved run. Useful for creating repeatable test scenarios, checkpointing before risky decisions, or regression testing bot strategies.

```bash
# Save current run
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"save","params":{"path":"/tmp/run_checkpoint.jkr"},"id":1}'
# → {"success": true, "path": "/tmp/run_checkpoint.jkr"}

# Load the saved run
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"load","params":{"path":"/tmp/run_checkpoint.jkr"},"id":1}'
# → {"success": true, "path": "/tmp/run_checkpoint.jkr"}

# Python: bracket a risky move with save/load
client.call("save", {"path": "/tmp/before_buy.jkr"})
try:
    state = client.call("buy", {"card": 0})
    if state["money"] < 0:
        client.call("load", {"path": "/tmp/before_buy.jkr"})
except Exception:
    client.call("load", {"path": "/tmp/before_buy.jkr"})
```
```

--------------------------------

### Proceed to Next Round from Shop

Source: https://context7.com/coder/balatrobot/llms.txt

Use the `next_round` method to exit the shop without making purchases and proceed to the blind selection phase, transitioning the state from `SHOP` to `BLIND_SELECT`.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"next_round","id":1}'
```

--------------------------------

### Advance to Next Round

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Use this to leave the shop and advance to the blind selection phase. This requires the game state to be SHOP.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "next_round", "id": 1}'
```

--------------------------------

### load

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Loads a saved game run from a file.

```APIDOC
## load

### Description
Load a saved run from a file.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Request Body
```json
{
  "jsonrpc": "2.0",
  "method": "load",
  "id": 1
}
```
```

--------------------------------

### load

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Loads a saved game run from a specified file path.

```APIDOC
## load

### Description
Load a saved run from a file.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version
- **method** (string) - Required - Method name, should be "load"
- **params** (object) - Required - Parameters for the method
  - **path** (string) - Required - Path to the save file
- **id** (integer) - Required - Request ID

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "load",
  "params": {"path": "/tmp/save.jkr"},
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC version
- **id** (integer) - Request ID
- **result** (object) - Result of the operation
  - **success** (boolean) - Indicates if the load was successful
  - **path** (string) - The path from which the save file was loaded

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "path": "/tmp/save.jkr"
  }
}
```
```

--------------------------------

### Configure Balatrobot via Environment Variables (PowerShell)

Source: https://github.com/coder/balatrobot/blob/main/docs/cli.md

Sets environment variables in PowerShell to configure the Balatrobot server's port and fast mode.

```powershell
$env:BALATROBOT_PORT = "8080"
$env:BALATROBOT_FAST = "1"
uvx balatrobot serve
```

--------------------------------

### Makefile Run All Tests

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Execute all project tests, including both CLI and Lua test suites.

```bash
make test
```

--------------------------------

### select

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Selects the current blind to begin the round. Requires the game state to be BLIND_SELECT.

```APIDOC
## select

### Description
Select the current blind to begin the round.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version
- **method** (string) - Required - Method name, should be "select"
- **id** (integer) - Required - Request ID

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "select",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - JSON-RPC version
- **id** (integer) - Request ID
- **result** (object) - Result of the operation
  - **state** (string) - Current game state, will be `SELECTING_HAND`

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "state": "SELECTING_HAND"
  }
}
```
```

--------------------------------

### Return to Main Menu

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Resets the game state to the main menu from any current state. This is a simple call with no parameters.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "menu", "id": 1}'
```

--------------------------------

### Discover RPC Methods

Source: https://context7.com/coder/balatrobot/llms.txt

Retrieve the full OpenRPC specification document to understand all available methods, parameters, and response types. This is useful for auto-generating clients or IDE completions.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"rpc.discover","id":1}' | jq '.methods[].name'
```

--------------------------------

### rpc.discover

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Returns the OpenRPC specification for this API.

```APIDOC
## rpc.discover

### Description
Returns the OpenRPC specification for this API.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Request Body
```json
{
  "jsonrpc": "2.0",
  "method": "rpc.discover",
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - The OpenRPC schema document.

### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}
```
```

--------------------------------

### Makefile Run All Quality Checks

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Execute all code quality checks, including linting, formatting, and type checking.

```bash
make quality
```

--------------------------------

### select

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Selects the current blind to begin the round.

```APIDOC
## select

### Description
Select the current blind to begin the round.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Request Body
```json
{
  "jsonrpc": "2.0",
  "method": "select",
  "id": 1
}
```
```

--------------------------------

### Call BalatroBot API Methods from CLI

Source: https://context7.com/coder/balatrobot/llms.txt

The `uvx balatrobot api` command allows direct interaction with the JSON-RPC API from the terminal. It wraps calls, prints results, and handles errors. Use `--port` and `--host` to target specific instances.

```bash
# Health check
uvx balatrobot api health

# Full game state (pipe through jq for readability)
uvx balatrobot api gamestate | jq '{state, ante_num, round_num, money}'

# Start a new run
uvx balatrobot api start '{"deck":"BLUE","stake":"WHITE","seed":"TEST1"}'

# Play cards at indices 0, 1, 2
uvx balatrobot api play '{"cards":[0,1,2]}'

# Get only the current state string
uvx balatrobot api gamestate | jq -r '.state'

# Show cards in hand
uvx balatrobot api gamestate | jq '.hand.cards | map({id,key,label})'

# Target a server on a non-default port
uvx balatrobot api gamestate --port 8080

# Error output goes to stderr, exit code 1
uvx balatrobot api play '{"cards":[999]}' 2>&1
# → Error: BAD_REQUEST - Card index 999 out of range
```

--------------------------------

### Play Cards at Specific Positions

Source: https://context7.com/coder/balatrobot/llms.txt

Use the `play` method to play cards from your hand. Specify the 0-based indices of the cards you wish to play.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"play","params":{"cards":[0,2,4]},"id":1}'
```

--------------------------------

### Screenshot Method

Source: https://context7.com/coder/balatrobot/llms.txt

Captures a screenshot of the current game state and saves it to a specified path. This can be invoked via HTTP POST request or through the CLI.

```APIDOC
## POST /screenshot

### Description
Captures a screenshot of the current game state and saves it to a specified path.

### Method
POST

### Endpoint
http://127.0.0.1:12346

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method name, should be "screenshot".
- **params** (object) - Required - Parameters for the screenshot method.
  - **path** (string) - Required - The absolute path where the screenshot will be saved.
- **id** (integer) - Required - A unique identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "screenshot",
  "params": {"path": "/abs/path/to/state.png"},
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **result** (object) - The result of the operation.
  - **success** (boolean) - Indicates if the screenshot was taken successfully.
  - **path** (string) - The absolute path to the saved screenshot.
- **id** (integer) - The identifier for the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {"success": true, "path": "/abs/path/to/state.png"},
  "id": 1
}
```
```

--------------------------------

### RPC Discover API Request

Source: https://github.com/coder/balatrobot/blob/main/docs/api.md

Retrieve the OpenRPC specification for the API.

```bash
curl -X POST http://127.0.0.1:12346 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "rpc.discover", "id": 1}'
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/coder/balatrobot/blob/main/docs/contributing.md

Commands to activate the Python virtual environment on macOS, Linux, and Windows.

```bash
source .venv/bin/activate
```

```powershell
.venv\Scripts\Activate.ps1
```