cliplatformer setup guide

cliplatformer guide.md

🚀 How to Install & Run the Shuffle CLI Platformer bot

Prerequisites:

• Windows, macOS, or Linux
• Node.js v18 or newer installed
  → You can check by opening Command Prompt (cmd) and typing:

  node -v
  npm -v

  If you see version numbers (e.g., v18.17.0), you’re good!
  If not, download Node.js here.

---

🔧 Step 1: Open the Project Folder in Terminal

1. Create folder and put files in it (e.g., into C:\cliplatformer).
2. Open Command Prompt (cmd) or PowerShell.
3. Navigate to the folder:

cd C:\cliplatformer

💡 Make sure this folder contains files like:

• cliplatformer.js
• package.json
• shuffle-api.js
• etc.

---

🔌 Step 2: Install Dependencies

Run this command to install all required packages:

npm install

✅ You should see output ending with something like:

added X packages in Ys

⚠️ If you get an error like 'npm' is not recognized, install Node.js first.

---

🔐 Step 3: Set Up Your Shuffle Credentials

The app needs your Shuffle.com API token and 2FA secret.

To setup bot

Just run:

node cliplatformer.js

The app will detect that shuffle-token.json is missing and ask you for:

• Your Bearer Token (from Shuffle.com Dev Tools)
• Your 2FA Secret (the base32 code from your authenticator app)
• Your Shuffle username

📝 Where to get your Bearer Token?

1. Open https://shuffle.com in Chrome
2. Press F12 → Network tab
3. Refresh the page
4. Click any GraphQL request (e.g., graphql)
5. In Headers, find Authorization: Bearer ey...
6. Copy everything after Bearer → that’s your token!

After answering all questions, the app will:

• Create shuffle-token.json
• Exit automatically

👉 Now run the app again:

node cliplatformer.js

Type a number or command (e.g., 4 for strategy selection) and press Enter. From dropped list, type strategy ID and press Enter. Type a number or command (e.g., 10 for Limbo) and press Enter.

💡 Hotkeys during Limbo:

• SPACE = Pause/Resume
• D/F = Halve/Double bet
• E/R = Halve/Double target
• Q = Quit session

---

🛑 Important Security Notes

• 🔒 Never share your shuffle-token.json — it contains secrets!

---

❓ Troubleshooting

Problem	Solution
Error: Cannot find module 'chalk'	Run npm install again
Invalid token	Double-check your Bearer token (must start with ey...)
2FA code invalid	Make sure your system clock is synced (TOTP is time-based)

---

🎲 Limbo Settings Configuration Guide

Last updated: February 2026

This document explains every supported field, action, condition, and value format usable in your limbo-settings.json strategy profiles — including multi-rule arrays, USD/% parsing, maxTarget enforcement, strategy switching, streak-based conditions, emulation mode, and hotkey controls.

---

🔧 Top-Level Structure

{
  "activeProfileIndex": 0,
  "profiles": [ /* array of profile objects */ ]
}

• activeProfileIndex: Integer. Index of the profile to use by default.
• profiles: Array of strategy profile objects (see below).

---

📁 Profile Object

Each profile has two top-level keys:

{
  "id": "UniqueStrategyId",
  "name": "My Strategy",
  "strategy": { /* strategy config */ }
}

• id: Required unique string ID used for switchStrategyId.
• name: Human-readable name (for UI only).
• strategy: The actual betting logic configuration.

💡 Tip: Use descriptive IDs like "Martingale_USD_v2" — they’re referenced during automatic strategy switching.

---

⚙️ Strategy Configuration (strategy)

✅ Core Fields

Field	Type	Description
enabled	boolean	If false, uses static CLI input instead of dynamic strategy.
baseBet	string	Starting bet amount. Supports: "0.01", "1 USD", "2.5%"
maxBetSize	string	Max allowed bet. Same formats as baseBet.
maxBetAction	string	One of: "stop", "reset", "reset-addbase", "switch_strategy"
maxTarget	number (optional)	Hard ceiling for target multiplier. Enforced per-bet.
maxTargetAction	string	One of: "stop", "reset", "reset-addtarget-base"

⚠️ Note: maxBetAction = "reset-addbase" increases base after each breach (e.g., 1× → 2× → 3× base).
switch_strategy requires switchStrategyId.

---

💡 USD & % Support

• "1 USD" → auto-converts to selected currency using live price fetched once per session.
• "2.5%" → uses 2.5% of starting balance in that currency (not recalculated mid-session).
• Works in: baseBet, maxBetSize, stopOnProfit, stopOnLoss, and rule value fields.

✅ Example: "baseBet": "0.5 USD" → if USDC = $1, bet = 0.5; if SHIB = $0.00001, bet = 50000.

---

🎯 Target Modes

Field	Type	Options / Notes
targetMode	string	"static", "random_range", "array_random"
staticTarget	string/number	e.g., "3.5"
randomTargetRange	object	{ "min": 2.0, "max": 10.0 }
targetArray	array	[200, 75, 50, 100]

• Only one mode is active at a time based on targetMode.
• If onWin/onLoss rules modify currentTarget, they override the mode unless targetMode !== "static" — then a new random/array target is regenerated each bet after rule application.

🔁 Exception: When switch_strategy activates, target is reinitialized from the new profile’s mode.

---

📈 Stop Conditions

Field	Type	Examples
stopOnProfit	string	"5", "10%", "25 USD"
stopOnLoss	string	"3", "15%", "10 USD"
switchStrategyId	array of strings	["Paroli_v2", "Martingale_USD"]

• If stop condition is met and switchStrategyId is non-empty → randomly switch to one of the listed profile IDs.
• If empty → session stops.
• USD/% thresholds use session-start prices/balance.

---

🔄 Bet & Target Adjustment Rules

✨ Multi-Rule Arrays (NEW)

Both onWin and onLoss now support arrays of rule objects:

"onWin": [
  {
    "action": "add_static_amount_to_current_bet",
    "condition": "after_each_2_wins",
    "value": "0.01 USD"
  },
  {
    "action": "return_to_base",
    "condition": "after_each_10_wins"
  }
]

✅ All matching rules are applied in order after each win/loss.

✅ Supported Bet Actions

Action	Description	value Format
"return_to_base"	Reset bet to baseBet	—
"increase_percent"	Multiply current bet by (1 + value/100)	number (e.g., 10)
"add_static_amount_to_base_bet"	baseBet += value	"0.5", "1 USD"
"add_static_amount_to_current_bet"	currentBet += value	same
"sub_static_amount_from_base_bet"	baseBet -= value	same
"sub_static_amount_from_current_bet"	currentBet -= value	same

🔒 All results clamped to ≥ minimum USD-equivalent of $0.001 (enforced in manual & auto modes).

✅ Supported Target Actions

Action	Description	value Format
"return_to_base_target"	Reset target to original base	—
"increase_percent_target"	Multiply target by (1 + value/100)	number
"add_static_amount_to_current_target"	currentTarget += value	number
"sub_static_amount_from_current_target"	currentTarget -= value	number

🎯 Targets always ≥ 1.01. If maxTarget is exceeded, maxTargetAction triggers.

---

📊 Condition Syntax

Used in condition field for rules.

Format	Trigger
"after_N_wins"	Once when total wins ≥ N
"after_N_lose"	Once when total losses ≥ N
"after_each_N_wins"	Every Nth win (2, 4, 6...)
"after_every_N_wins"	Alias for after_each_N_wins
(omitted or null)	Apply every time

🔢 Counts are cumulative across the entire session.
Streaks are tracked via StreakTracker class (supports complex win/loss sequences).

---

🔄 Strategy Switching

• Triggered by:
  • maxBetAction: "switch_strategy"
  • stopOnProfit / stopOnLoss with switchStrategyId
• Selects random profile ID from switchStrategyId array.
• On switch:
  • baseBet and currentBet are re-parsed (USD/% resolved)
  • startBalance resets to current balance
  • Target is reinitialized per new profile’s targetMode

❗ Profile must exist in profiles array. Missing ID → session aborts.

---

🎮 Hotkey Controls (Manual Mode Only)

In manual_limbo and manual_mines, these keys work during active session:

Key	Action
SPACE	Place bet / pick tile
D	Halve bet (min $0.001 USD)
F	Double bet
E	Halve target (min 1.01x)
R	Double target
S	Skip round (place $0.001 @ 1.01x, grey log)
Q	Quit manual mode
C	(Mines only) Cash out

💡 Bet adjustments respect USD-equivalent minimum automatically.

---

🧪 Emulation Mode

Enable via shuffle-token.json:

{
  "emulation_mode": true,
  "emulation_balance": 50
}

• Uses deterministic SHA-256 HMAC roll emulation (client-side)
• No real API calls
• Balance updates simulated
• Great for testing strategies risk-free

---

📝 Example Full Profile (Modern Syntax)

{
  "id": "Hybrid_Recovery_v3",
  "name": "Hybrid Recovery v3",
  "strategy": {
    "enabled": true,
    "baseBet": "0.01 USD",
    "maxBetSize": "0.5 USD",
    "maxBetAction": "switch_strategy",
    "maxTarget": 1500,
    "maxTargetAction": "reset",
    "stopOnProfit": "30 USD",
    "stopOnLoss": "15 USD",
    "switchStrategyId": ["Martingale_USD", "Paroli_v2"],

    "targetMode": "static",
    "staticTarget": "40",

    "onWin": [
      {
        "action": "add_static_amount_to_current_bet",
        "condition": "after_each_3_wins",
        "value": "0.005 USD"
      },
      {
        "action": "return_to_base",
        "condition": "after_each_20_wins"
      }
    ],
    "onLoss": [
      {
        "action": "add_static_amount_to_current_bet",
        "condition": "after_each_5_lose",
        "value": "0.002 USD"
      }
    ]
  }
}