____            _ _ _        ____ _     ___ 
 |  _ \ ___ _ __ | (_) |_     / ___| |   |_ _|
 | |_) / _ \ '_ \| | | __|   | |   | |    | | 
 |  _ <  __/ |_) | | | |_    | |___| |___ | | 
 |_| \_\___| .__/|_|_|\__|    \____|_____|___|
           |_|                                

⚡ Direct Terminal Shell & Remote Container Control for Replit ⚡

Use Replit from your local terminal just like GitHub Codespaces, SSH, or a local Linux VM.
Interactive bash shells, remote command runners, bidirectional file sync (replit cp), and self-healing diagnostics (replit doctor).

---

Quick Start • Features • Command Reference • How It Works • Troubleshooting • Contributing

---

🚀 Key Features

• 🖥️ Interactive Terminal Shell (replit shell): Drop straight into a full remote bash shell inside your Replit container with live terminal rendering and remote directory tracking.
• ⚡ One-Off Command Execution (replit exec): Run arbitrary commands and pipelines remotely with instant output streaming (replit exec "uname -a; python3 app.py").
• 🩺 Automated Health Diagnostics (replit doctor): 5-point self-healing suite verifying DNS, edge latency, cookie validity, PASETO token generation, and WebSocket cluster connectivity.
• 📂 Bidirectional File Sync (replit cp): Copy files between your local workstation and remote Repl container seamlessly (replit cp ./local.js repl:src/local.js).
• 🔄 Multi-Repl Manager (replit create / list / use): Create new environments (Python, Bash, Nix) and switch active containers with a single command.
• 🌐 Universal & Cross-Platform: Works natively on Linux, macOS (Intel & Apple Silicon), Windows (PowerShell & WSL), Android Termux, Docker, and headless CI/CD.

---

⚡ Quick Start

1. Installation

Clone and link the CLI globally:

git clone https://github.com/The-habib/replit-shell.git replit-cli
cd replit-cli
npm install -g .

(Alternatively, run directly with Bun or Node without installation):

node tools/replit-cli/bin/replit.js --help

---

2. Authenticate in 30 Seconds

replit login

The CLI will prompt you to paste your Replit session cookie (connect.sid).

🔍 How to find your connect.sid cookie (Click to expand)

1. Open https://replit.com in your web browser and ensure you are logged in.
2. Press F12 (or Right-Click → Inspect) to open Browser DevTools.
3. Go to the Application tab (Chrome / Brave / Edge) or Storage tab (Firefox / Safari).
4. In the left sidebar, expand Cookies and click on https://replit.com.
5. Locate the cookie named connect.sid and copy its full value.
6. Paste it into the replit login prompt or run:

   replit auth set "connect.sid=eyJhbGci..."

💡 Pro-tip for CI/CD & Docker: Set the REPLIT_COOKIE environment variable to authenticate non-interactively without storing files on disk.

---

3. Verify System Health

Run the diagnostic suite:

replit doctor

  🩺 Replit CLI System Diagnostics (replit doctor)

  ✔ OK    Local Runtime & Platform
         Node.js v24.14.0 on linux (x64)

  ✔ OK    Replit Edge Reachability
         Connected to replit.com (293ms latency, HTTP 200)

  ✔ OK    Authentication & Session Cookie
         Authenticated as Replit User ID: 63578078

  ✔ OK    Container Metadata Gateway (/data/repls)
         Repl [34c84b77] resolved -> Dev Host: 34c84b77-....replit.dev

  ✔ OK    Container Cluster Protocol (Goval/Crosis)
         PASETO Token minted, Cluster Gateway: wss://eval.pike.platform.replit.com

  🎉 All diagnostic checks passed! Your Replit CLI is ready to rock.

---

💻 Usage & Examples

1. Interactive Shell Session

replit shell

runner@repl:~/workspace$ uname -a
Linux repl 6.18.44 #Replit-Linux SMP Sun Aug 9 18:25:30 UTC 2026 x86_64 GNU/Linux
runner@repl:~/workspace$ python3 --version
Python 3.11.14

2. Execute Remote Commands

# Run one-off commands
replit exec "ls -la"

# Run complex build pipelines
replit exec "python3 -m pip install requests && python3 test_suite.py"

3. Transfer Files

# Upload local file into container
replit cp ./server.py repl:src/server.py

# Download remote file to local machine
replit cp repl:output.log ./local_output.log

4. Create and Switch Environments

# Create a new Python 3 environment
replit create "data-pipeline" --lang python3

# List all accessible Repls
replit list

# Switch default active Repl
replit use <repl-id>

---

📖 CLI Command Reference

Command	Description	Example
replit shell [replId]	Opens interactive terminal shell with directory tracking	replit shell
replit exec "<command>"	Executes remote command and streams stdout/stderr	replit exec "uname -a"
replit doctor	Runs 5-point automated connectivity and health checks	replit doctor
replit cp <src> <dest>	Bidirectional file transfer between workstation and Repl	replit cp ./app.py repl:app.py
replit login [cookie]	Interactive setup wizard for authentication	replit login
replit logout	Clears stored session credentials	replit logout
replit whoami	Shows authenticated user identity and active container	replit whoami
replit create <title> [-l lang]	Creates a new Repl container (python3, bash, nix)	replit create my-app -l bash
replit list	Lists all saved Repls with active status indicators	replit list
replit use <replId>	Switches active default Repl	replit use 34c84b77...
replit info [replId]	Inspects cluster WebSocket URLs and PASETO tokens	replit info
replit auth show|set	Inspects or updates session cookie configuration	replit auth show

---

🔬 How It Works: Reverse-Engineered Protocol

sequenceDiagram
    autonumber
    actor Dev as Developer (Local Terminal)
    participant CLI as Replit CLI Engine
    participant GQL as Replit GraphQL (APQ)
    participant Lore as Metadata Service (/data/repls)
    participant Cluster as Goval Container Cluster (Crosis)

    Dev->>CLI: replit exec "uname -a"
    CLI->>GQL: Verify connect.sid via SHA-256 APQ Link
    GQL-->>CLI: User Authenticated (uid: 63578078)
    CLI->>Lore: POST /data/repls/:id/get_connection_metadata
    Lore-->>CLI: Return PASETO Token & wss://eval.*.platform.replit.com
    CLI->>Cluster: WebSocket Connect + Channel 0 Handshake
    CLI->>Cluster: Open Exec Channel { args: ["bash", "-c", "uname -a"] }
    Cluster-->>Dev: Real-time stdout & stderr stream + exit code

Loading

1. Automatic Persisted Queries (APQ): Replit's GraphQL gateway (https://replit.com/graphql) requires SHA-256 precompiled query hashes and custom client headers (X-Requested-With: XMLHttpRequest, X-Client-Version: f04c140b).
2. Metadata & PASETO Minting: The CLI talks to /data/repls/:replId/get_connection_metadata to dynamically resolve cluster routing hostnames and generate temporary PASETO v2 container authorization tokens.
3. Crosis Multiplexed WebSocket Protocol: Connects to wss://eval.<cluster>.platform.replit.com/wsv2/<paseto_token>, binds to channel 0 (chan0), and multiplexes exec and pty channels for bidirectional terminal streaming.

---

🛠️ Troubleshooting

If you encounter issues such as session expiration, container wake-up latency, or missing Nix packages, consult the dedicated guide:

👉 Read TROUBLESHOOTING.md

Common quick fixes:

• Session Expired: Run replit login and paste a fresh connect.sid.
• Container Sleeping: Add --timeout 60000 to replit exec.
• Self-Diagnostics: Run replit doctor to pinpoint the exact failure point.

---

📱 Cross-Platform Matrix

Platform	Support	Notes
🐧 Linux (x86_64, ARM64)	✅ Full	Ubuntu, Debian, Fedora, Arch, Alpine
🍎 macOS (Apple Silicon & Intel)	✅ Full	Terminal, iTerm2, Warp, Ghostty
🪟 Windows (PowerShell, CMD, WSL)	✅ Full	Windows Terminal recommended
📱 Android Termux	✅ Full	Run remote shells directly from mobile
🐳 Docker & CI/CD	✅ Full	Headless automation via REPLIT_COOKIE

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md for local development instructions.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.