STS2 CLI Mod

A CLI control mod for Slay the Spire 2. Enables AI agents (or human scripters) to observe game state and execute actions entirely from the command line.

Two independent .NET 9 / C# projects communicate via Named Pipe with JSON messages:

AI Agent ──> sts2 CLI ──Named Pipe──> In-Game Mod ──> Game

STS2.Cli.Mod — An in-process game mod that runs inside the Godot engine, reads game state and executes actions on behalf of the CLI.
STS2.Cli.Cmd — A standalone CLI tool (sts2 / sts2.exe) that sends commands over the pipe and prints JSON responses to stdout.

Features

Full game state extraction — Query the complete game state as structured JSON: combat (hand, enemies, intents, powers, draw/discard/exhaust piles), map, events, shop, rewards, rest sites, and more.
Action execution — Play cards, use potions, end turns, navigate the map, pick rewards, buy from shops, choose event options, and handle every game screen.
16+ screen types detected — Combat, Map, Event, Shop, Reward, Rest Site, Treasure, Character Select, Crystal Sphere mini-game, and others.
40+ commands — Covering the full game flow from main menu to game over.
Structured JSON protocol — All responses follow {"ok": true, "data": {...}} / {"ok": false, "error": "CODE", "message": "..."} format with snake_case naming.
Cross-platform CLI — Windows, macOS (Intel & Apple Silicon), and Linux builds. WSL fully supported. (Note: macOS and Linux support is currently untested.)

Installation

One-Line Install

Windows (PowerShell):

irm https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.ps1 | iex

WSL / macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.sh | bash

The scripts automatically:

Detect your Steam game directory (including custom Steam library folders)
Download the latest CLI and Mod from GitHub Releases
Install the CLI to your PATH (Windows: %LOCALAPPDATA%\sts2-cli, macOS/Linux: ~/.local/bin)
Deploy the Mod to the game's mods/ directory

WSL note: The CLI is installed to the Windows side (%LOCALAPPDATA%\sts2-cli\sts2.exe) with a bash alias, since the game and Named Pipe run on Windows.

Install a Specific Version

PowerShell:

$env:STS2_VERSION="0.102.1"; irm https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.ps1 | iex

bash:

curl -fsSL https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.sh | bash -s -- -v 0.102.1

Uninstall

PowerShell:

$env:STS2_UNINSTALL="1"; irm https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.ps1 | iex

bash:

curl -fsSL https://raw.githubusercontent.com/longkerdandy/STS2-Cli-Mod/main/install.sh | bash -s -- --uninstall

Manual Install

Download the latest release from GitHub Releases:

CLI — sts2-cli-v{version}-{platform}.zip (or .tar.gz). Extract and add to your PATH.
Mod — sts2-mod-v{version}.zip. Extract STS2.Cli.Mod.dll and STS2.Cli.Mod.json into <game directory>/mods/.

Quick Start

Launch Slay the Spire 2 with mods enabled
Open a terminal and verify the connection:

sts2 ping
# {"ok":true,"data":{"connected":true}}

Query the current game state:

sts2 state -p

Execute actions based on the current screen:

# Start a new run
sts2 new_run
sts2 select_character ironclad
sts2 embark

# Navigate the map
sts2 choose_map_node 3 1

# Play cards in combat
sts2 play_card STRIKE --target 0
sts2 play_card DEFEND
sts2 end_turn

# Use a potion
sts2 use_potion FIRE_POTION --target 0

Commands

All commands output JSON to stdout. Use --pretty / -p for human-readable formatting.

Exit codes: 0 = success, 1 = connection error, 2 = invalid state, 3 = invalid parameter, 4 = timeout, 5 = state changed.

For the full command reference with detailed parameters and response formats, see docs/cli-reference.md.

Connection & State

Command	Description
`ping`	Test connection to the mod
`state`	Get current game state as JSON

Main Menu

Command	Description
`new_run`	Start a new game
`continue_run`	Continue a saved run
`abandon_run`	Abandon the saved run
`choose_game_mode <mode>`	Select game mode (standard, daily, custom)

Character Select

Command	Description
`select_character <id>`	Select a character
`set_ascension <level>`	Set ascension level (0-20)
`embark`	Start the run

Combat

Command	Description
`play_card <card_id> [--target <combat_id>]`	Play a card from hand
`end_turn`	End the current turn
`use_potion <potion_id> [--target <combat_id>]`	Use a potion
`hand_select_card <card_id> [...]`	Select cards from hand (discard, exhaust, etc.)
`hand_confirm_selection`	Confirm hand card selection
`grid_select_card <card_id> [...]`	Select cards from grid (remove, upgrade, etc.)
`grid_select_skip`	Skip grid card selection

Map & Navigation

Command	Description
`choose_map_node <col> <row>`	Travel to a map node
`proceed`	Leave current screen and go to map

Rewards

Command	Description
`reward_claim --type <type> [--id <id>]`	Claim a reward (gold, potion, relic)
`reward_choose_card --card_id <id>`	Pick a card reward
`reward_skip_card`	Skip a card reward

Events

Command	Description
`choose_event <index>`	Choose an event option
`advance_dialogue [--auto]`	Advance dialogue in Ancient events

Card Selection Screens

Command	Description
`tri_select_card <card_id> [...]`	Select from three-choose-one
`tri_select_skip`	Skip three-choose-one selection

Rest Site

Command	Description
`choose_rest_option <option_id>`	Choose rest option (HEAL, SMITH, etc.)

Treasure Room

Command	Description
`open_chest`	Open the treasure chest
`pick_relic <index>`	Pick a relic from the chest

Shop

Command	Description
`shop_buy_card <card_id>`	Buy a card
`shop_buy_relic <relic_id>`	Buy a relic
`shop_buy_potion <potion_id>`	Buy a potion
`shop_remove_card`	Buy card removal service

Relic & Bundle Selection

Command	Description
`relic_select <index>`	Select a relic from boss/event choice
`relic_skip`	Skip relic selection
`bundle_select <index>`	Preview a bundle (Scroll Boxes relic)
`bundle_confirm`	Confirm bundle selection
`bundle_cancel`	Cancel bundle preview

Crystal Sphere

Command	Description
`crystal_set_tool <tool>`	Switch tool (big / small)
`crystal_click_cell <x> <y>`	Click a cell to clear fog
`crystal_proceed`	Leave the mini-game

Game Over

Command	Description
`return_to_menu`	Return to main menu

Utility

Command	Description
`report_bug --title <t> --description <d>`	Save a structured bug report locally

Architecture

STS2-Cli-Mod/
├── STS2.Cli.Cmd/         # Standalone CLI tool
│   ├── Commands/          #   Command definitions (System.CommandLine)
│   ├── Client/            #   Named Pipe client
│   └── Models/            #   Request/Response DTOs
├── STS2.Cli.Mod/          # In-process game mod
│   ├── Actions/           #   Action handlers (play_card, end_turn, ...)
│   ├── State/Builders/    #   State extraction (combat, map, event, ...)
│   ├── Server/            #   Named Pipe server
│   ├── Models/            #   Request + State DTOs
│   └── Utils/             #   Thread marshalling, JSON, logging
├── install.ps1            # Windows installer
├── install.sh             # WSL / macOS / Linux installer
└── docs/
    └── cli-reference.md   # Full command reference

The two projects share no code. They communicate exclusively through a Named Pipe (sts2-cli-mod) using JSON messages. The mod runs inside the Godot 4.5.1 engine and marshals all game state access to the main thread.

Building from Source

Requires .NET 9 SDK and a local copy of Slay the Spire 2.

# Build the Mod (auto-deploys to game mods/ directory)
dotnet build STS2.Cli.Mod/STS2.Cli.Mod.csproj -c Release

# Publish the CLI as a single-file executable
dotnet publish STS2.Cli.Cmd/STS2.Cli.Cmd.csproj -c Release -r win-x64

Supported runtime identifiers: win-x64, osx-x64, osx-arm64, linux-x64.

Related Projects

Project	Description
STS2MCP	MCP-based AI agent control for STS2
SLS2Mods	HarmonyX patching examples for STS2
spire-codex	Full game data via decompilation

License

This project is not affiliated with Mega Crit Games.

Name		Name	Last commit message	Last commit date
Latest commit History 205 Commits
.github/workflows		.github/workflows
STS2.Cli.Cmd		STS2.Cli.Cmd
STS2.Cli.Mod		STS2.Cli.Mod
docs		docs
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Directory.Build.props		Directory.Build.props
README.md		README.md
STS2-Cli-Mod.sln		STS2-Cli-Mod.sln
STS2-Cli-Mod.slnx		STS2-Cli-Mod.slnx
install.ps1		install.ps1
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

STS2 CLI Mod

Features

Installation

One-Line Install

Install a Specific Version

Uninstall

Manual Install

Quick Start

Commands

Connection & State

Main Menu

Character Select

Combat

Map & Navigation

Rewards

Events

Card Selection Screens

Rest Site

Treasure Room

Shop

Relic & Bundle Selection

Crystal Sphere

Game Over

Utility

Architecture

Building from Source

Related Projects

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

STS2 CLI Mod

Features

Installation

One-Line Install

Install a Specific Version

Uninstall

Manual Install

Quick Start

Commands

Connection & State

Main Menu

Character Select

Combat

Map & Navigation

Rewards

Events

Card Selection Screens

Rest Site

Treasure Room

Shop

Relic & Bundle Selection

Crystal Sphere

Game Over

Utility

Architecture

Building from Source

Related Projects

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages