Skip to main content
The Crimsonland reimplementation exposes all functionality through a comprehensive command-line interface built with Typer.

​
Installation

# Install latest from PyPI
uvx crimsonland@latest

# Run from source
gh repo clone banteg/crimson && cd crimson
uv run crimson

​
Entry Points

The package provides two equivalent entry points:
  • crimson — primary CLI entry point
  • crimsonland — alias for compatibility
Both commands provide identical functionality.

​
Command Structure

The CLI is organized into logical command groups: 
crimson                    # Run game (default command)
crimson extract            # Extract PAQ archives
crimson config             # Inspect crimson.cfg
crimson view               # Debug views
crimson quests             # Quest spawn scripts
crimson spawn-plan         # Spawn plan builder

crimson replay list        # List replays
crimson replay play        # Play replay
crimson replay verify      # Verify replay
crimson replay render      # Render to video
crimson replay benchmark   # Benchmark performance
crimson replay info        # Extract timeline

crimson dbg record         # Record CDT trace
crimson dbg health         # Trace health check
crimson dbg verify         # Verify schema
crimson dbg diff           # Compare traces
crimson dbg bisect         # Bisect divergence
crimson dbg tick           # Inspect tick
crimson dbg entity         # Entity history
crimson dbg query          # Query DSL
crimson dbg focus          # Focus tick report
crimson dbg viz            # HTML visualization

crimson net host           # Host network session
crimson net join           # Join session

crimson relay serve        # Run relay server

​
Global Options

These options are available across most commands:
​
--base-dir
Path
Base path for runtime files (saves, config, logs, replays). Defaults to per-user OS data directory.Override with CRIMSON_RUNTIME_DIR environment variable.
​
--assets-dir
Path
Assets root directory (PAQ files or extracted assets). Defaults to base-dir.Missing .paq files are automatically downloaded.
​
--help
flag
Show help message and exit.

​
Environment Variables

​
CRIMSON_RUNTIME_DIR
string
Override default runtime directory location.
export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
crimson

​
Exit Codes

  • 0 — Success
  • 1 — General error (file not found, parse error, etc.)
  • 2 — Query syntax error (dbg query)
  • 3 — Replay verification score mismatch

​
Output Formats

Many commands support multiple output formats:
  • --format human — Human-readable text (default)
  • --format json — Machine-readable JSON
  • --json-out <path> — Write JSON to file

​
Common Patterns

​
Run with Custom Runtime Directory

# Keep everything local to checkout
export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
crimson

​
Extract Original Game Assets

crimson extract path/to/game_dir artifacts/assets

​
Deterministic Seeded Run

crimson --seed 12345 --no-intro

​
Shareware Demo Mode

crimson --demo

​
Enable Debug Features

crimson --debug  # Cheats and overlays

​
Platform Notes

​
Wayland on Linux

Current PyPI raylib wheels are X11-oriented on x86_64. You may need: 
sudo apt install xwayland libx11-6
See raylib-python-cffi#199 for details.

​
Next Steps

Run Command

Launch the game with custom settings

Replay System

Record, verify, and render replays

Extract Archives

Extract PAQ archives to filesystem

Debug Tools

Debug views and trace tools

Build docs developers (and LLMs) love

Get started for freeTalk to us