|
| 1 | +# CLI Reference |
| 2 | + |
| 3 | +Reference for the `balatrollm` command-line interface. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +```bash |
| 8 | +balatrollm [CONFIG] [OPTIONS] |
| 9 | +``` |
| 10 | + |
| 11 | +BalatroLLM can be configured through three methods with the following precedence (lowest to highest): |
| 12 | + |
| 13 | +1. **Environment variables** - `BALATROLLM_*` prefixed variables |
| 14 | +2. **Configuration file** - YAML file (see [`config/example.yaml`](https://github.com/coder/balatrollm/blob/main/config/example.yaml)) |
| 15 | +3. **CLI flags** - Command-line arguments (highest precedence) |
| 16 | + |
| 17 | +This means CLI flags override config file values, which override environment variables. |
| 18 | + |
| 19 | +## Arguments |
| 20 | + |
| 21 | +| Argument | Required | Description | |
| 22 | +| -------- | -------- | ------------------------------- | |
| 23 | +| `CONFIG` | No | Path to YAML configuration file | |
| 24 | + |
| 25 | +## Options |
| 26 | + |
| 27 | +| CLI Flag | Environment Variable | Default | Description | |
| 28 | +| --------------------- | --------------------- | ------------------------------ | ---------------------------- | |
| 29 | +| `--model MODEL` | `BALATROLLM_MODEL` | *(required)* | LLM model(s) to use | |
| 30 | +| `--seed SEED` | `BALATROLLM_SEED` | `AAAAAAA` | Game seed(s) | |
| 31 | +| `--deck DECK` | `BALATROLLM_DECK` | `RED` | Deck code(s) | |
| 32 | +| `--stake STAKE` | `BALATROLLM_STAKE` | `WHITE` | Stake code(s) | |
| 33 | +| `--strategy STRATEGY` | `BALATROLLM_STRATEGY` | `default` | Strategy name(s) | |
| 34 | +| `--parallel N` | `BALATROLLM_PARALLEL` | `1` | Concurrent game instances | |
| 35 | +| `--host HOST` | `BALATROLLM_HOST` | `127.0.0.1` | BalatroBot host | |
| 36 | +| `--port PORT` | `BALATROLLM_PORT` | `12346` | Starting port | |
| 37 | +| `--base-url URL` | `BALATROLLM_BASE_URL` | `https://openrouter.ai/api/v1` | LLM API base URL | |
| 38 | +| `--api-key KEY` | `BALATROLLM_API_KEY` | *None* | LLM API key | |
| 39 | +| `--dry-run` | - | `False` | Show tasks without executing | |
| 40 | + |
| 41 | +!!! note "Multiple Values" |
| 42 | + |
| 43 | + Options marked with "model(s)", "seed(s)", etc. accept multiple values. When multiple values are provided, BalatroLLM generates a cartesian product of all combinations as tasks. |
| 44 | + |
| 45 | +The following values can be provided for `deck` and `stake` options: |
| 46 | + |
| 47 | +- **Decks:** `RED`, `BLUE`, `YELLOW`, `GREEN`, `BLACK`, `MAGIC`, `NEBULA`, `GHOST`, `ABANDONED`, `CHECKERED`, `ZODIAC`, `PAINTED`, `ANAGLYPH`, `PLASMA`, `ERRATIC` |
| 48 | +- **Stakes:** `WHITE`, `RED`, `GREEN`, `BLACK`, `BLUE`, `PURPLE`, `ORANGE`, `GOLD` |
| 49 | + |
| 50 | +## Examples |
| 51 | + |
| 52 | +### Basic Usage |
| 53 | + |
| 54 | +```bash |
| 55 | +# Run with specific model (requires BALATROLLM_API_KEY in environment) |
| 56 | +balatrollm --model openai/gpt-5 |
| 57 | + |
| 58 | +# Run with configuration file |
| 59 | +balatrollm config/example.yaml |
| 60 | + |
| 61 | +# Run with config file and override specific options |
| 62 | +balatrollm config/example.yaml --model openai/gpt-5 --seed BBBBBBB |
| 63 | +``` |
| 64 | + |
| 65 | +### Advanced Usage |
| 66 | + |
| 67 | +```bash |
| 68 | +# Multiple seeds and decks (generates cartesian product of all combinations) |
| 69 | +balatrollm --model openai/gpt-5 --deck RED BLUE --seed AAAAAAA BBBBBBB |
| 70 | + |
| 71 | +# Run multiple game instances concurrently |
| 72 | +balatrollm --model openai/gpt-5 --parallel 4 |
| 73 | + |
| 74 | +# Preview tasks without executing |
| 75 | +balatrollm config/example.yaml --dry-run |
| 76 | + |
| 77 | +# Use a custom strategy |
| 78 | +balatrollm --model openai/gpt-4o --strategy my_custom_strategy |
| 79 | +``` |
| 80 | + |
| 81 | +!!! note "Cartesian Product" |
| 82 | + |
| 83 | + When specifying multiple values for seeds, decks, stakes, etc., BalatroLLM generates all combinations as separate tasks. For example, `--deck RED BLUE --seed AAAAAAA BBBBBBB` creates 4 tasks: `(RED, AAAAAAA)`, `(RED, BBBBBBB)`, `(BLUE, AAAAAAA)`, `(BLUE, BBBBBBB)`. For complex task configurations, use a YAML configuration file. |
| 84 | + |
| 85 | +For more information about strategies, see the [Strategies documentation](strategies.md). |
| 86 | + |
| 87 | +## BalatroBot Configuration |
| 88 | + |
| 89 | +BalatroBot instances spawned by BalatroLLM can be configured through `BALATROBOT_*` environment variables. These settings control how Balatro runs during automated gameplay. |
| 90 | + |
| 91 | +| Environment Variable | Default | Description | |
| 92 | +| -------------------------- | ------------- | ------------------------------------------ | |
| 93 | +| `BALATROBOT_HOST` | `127.0.0.1` | Server hostname | |
| 94 | +| `BALATROBOT_PORT` | `12346` | Server port | |
| 95 | +| `BALATROBOT_FAST` | `0` | Enable fast mode (10x game speed) | |
| 96 | +| `BALATROBOT_HEADLESS` | `0` | Enable headless mode (minimal rendering) | |
| 97 | +| `BALATROBOT_RENDER_ON_API` | `0` | Render only on API calls | |
| 98 | +| `BALATROBOT_AUDIO` | `0` | Enable audio | |
| 99 | +| `BALATROBOT_DEBUG` | `0` | Enable debug mode (requires DebugPlus mod) | |
| 100 | +| `BALATROBOT_NO_SHADERS` | `0` | Disable all shaders | |
| 101 | +| `BALATROBOT_BALATRO_PATH` | auto-detected | Path to Balatro game directory | |
| 102 | +| `BALATROBOT_LOVELY_PATH` | auto-detected | Path to lovely library (dll/so/dylib) | |
| 103 | +| `BALATROBOT_LOVE_PATH` | auto-detected | Path to LOVE executable (native only) | |
| 104 | +| `BALATROBOT_PLATFORM` | auto-detected | Platform: darwin, linux, windows, native | |
| 105 | +| `BALATROBOT_LOGS_PATH` | `logs` | Directory for log files | |
| 106 | + |
| 107 | +For detailed information about platform-specific behavior and configuration, see the [BalatroBot Platform-Specific Details](https://coder.github.io/balatrobot/cli/#platform-specific-details) |
0 commit comments