<p align="center">
<img src="assets/logo.svg" alt="Limitless CLI Logo" width="220" />
</p>
<h1 align="center">๐ Limitless CLI</h1>
<p align="center">
<b>The Intelligent, Stack-Aware Development Environment Pre-flight Engine & Auto-Repair Suite</b>
</p>
<p align="center">
<a href="https://crates.io/crates/limitless-cli"><img src="https://img.shields.io/badge/crates.io-v1.0.0-orange.svg?style=for-the-badge&logo=rust" alt="Crates.io"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge" alt="License"></a>
<a href="https://www.rust-lang.org"><img src="https://img.shields.io/badge/rust-1.75%2B-brightgreen.svg?style=for-the-badge&logo=rust" alt="Rust Version"></a>
<a href="#"><img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg?style=for-the-badge" alt="Platforms"></a>
</p>
<p align="center">
<a href="#-why-limitless">Why Limitless?</a> โข
<a href="#-feature-showcase">Feature Showcase</a> โข
<a href="#-installation">Installation</a> โข
<a href="#-command-cheatsheet">Command Cheatsheet</a> โข
<a href="#-stack-detection-matrix">Stack Matrix</a> โข
<a href="#-gamification--badges">Badges</a> โข
<a href="#-configuration">Configuration</a>
</p>
---
## ๐ก Why Limitless?
Ever spent 45 minutes debugging why your app won't launch, only to realize:
* ๐ด **Port 5432 or 27017** was silently hijacked by a ghost PostgreSQL/MongoDB process?
* ๐ด Your local **`.env`** file was missing required keys present in `.env.example`?
* ๐ด **`node_modules`** was out of sync with `package-lock.json` or `pnpm-lock.yaml`?
* ๐ด Your system **`PATH`** contained 13 duplicate folders and 4 broken paths?
**Limitless CLI (`limit`)** runs **19+ concurrent pre-flight checks in milliseconds**, scores your environment health (0โ100%), translates cryptic OS errors into plain English mentor advice, and automatically applies fixes safely.
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ LIMITLESS v1.0.0 โ SYSTEM ENVIRONMENT PRE-FLIGHT โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ [โ] Env Audit: .env file matches .env.example โ
โ [โ] Dependency audit: manifest and lock file are present โ
โ [โ] Runtime Check: Node v22.23.2 meets recommended version (>= 18.0.0) โ
โ [โ] Port 5432: Port 5432 is occupied by PID 6460 (postgres) โ
โ [โ] Port 27017: Port 27017 is occupied by PID 4620 (mongod) โ
โ [โ] Tool rustc: rustc 1.98.0 โ
โ [โ] Tool node: node v22.23.2 โ
โ [โ] Tool go: go version go1.26.3 windows/amd64 โ
โ โ
โ Health Score: 68% [โโโโโโโโโโโโโโโโโโโโ] โ
โ Status: CAUTION โ
โ โ
โ ๐ก MENTOR NOTE: โ
โ No default editor is configured, so command-line tools may pick a โ
โ random one or fail. It's like having mail delivered but no default โ
โ address on file. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
---
## โจ Feature Showcase
### 1. ๐ Full Environment Pre-Flight Audit (`limit`)
Scans runtime versions, process tables, lockfiles, proxy configurations, and PATH hygiene simultaneously using Rust's async Tokio worker threads.
### 2. ๐ก๏ธ Pre-Flight Dev Server Launcher (`limit dev`)
Performs a deep audit before starting your development server. If health is 100%, it automatically spawns the project's dev server (`npm run dev`, `cargo run`, `python main.py`, `go run .`, etc.). If unhealthy, it halts launch to prevent infinite crash loops and highlights the fix.
### 3. ๐ง Automated & Interactive Fix Suite (`limit fix`)
* **Interactive Mode (`limit fix`):** Prompts for approval step-by-step before modifying system state.
* **Automated Mode (`limit fix --all`):** Terminates port-blocking PIDs, generates `.env` files from `.env.example`, repairs missing `.gitignore`/`.editorconfig`, and installs out-of-sync dependencies. Includes permission guards for elevated Windows/Unix processes.
### 4. ๐ Planetary Mission Control Mode (`limit orbit`)
Renders environment diagnostics inside a retro sci-fi space station telemetry dashboard:
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ PLANETARY MODE โ MISSION CONTROL REPORT โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ ๐ก๏ธ Shield Generator (.env) โ
โ [โ] Status: OPERATIONAL โ
โ โ
โ ๐ง System Components Bay (node_modules/) โ
โ [โ ] Status: MINOR ALERT โ
โ โ Run `npm list` to check dependency health โ
โ โ
โ Mission Health: 68% [โโโโโโโโโโโโโโโโโโโโ] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### 5. โ๏ธ SyntaxBreaker Arcade Game (`limit arcade`)
A built-in terminal typing arcade game featuring developer code snippets, real-time WPM/accuracy tracking, live timers, and persistent top-5 high scores saved to disk.
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ๏ธ SYNTAXBREAKER ARCADE GAME โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Type the code snippet: โ
โ function hello() { } โ
โ โ
โ Your input: function hello()_ โ
โ โ
```
---
## โก Installation
### Option A: Via Cargo (Recommended)
```bash
# Build and install globally from source
cargo install --path .
# Or install directly from Crates.io
cargo install limitless-cli
```
### Option B: Build from Source
```bash
git clone https://github.com/limitless-cli/limitless.git
cd limitless
cargo build --release
```
*For platform-specific installation scripts (Homebrew, APT, Chocolatey), see [`docs/INSTALLATION.md`](docs/INSTALLATION.md).*
---
## ๐ Command Cheatsheet
```bash
limit # Run full environment audit
limit dev # Pre-flight check + dev server launch (when healthy)
limit fix --all # Automatically resolve all detected issues
limit orbit # Sci-fi mission-control diagnostic dashboard
limit arcade # Launch SyntaxBreaker typing minigame
limit --help # Render built-in terminal documentation
```
### Global Execution Flags
| **`--fast`** / **`-f`** | Skips animations and spinners for instant result rendering. |
| **`--verbose`** / **`-v`** | Outputs technical telemetry behind every check, including full error stack traces. |
| **`--no-color`** | Disables ANSI color output (useful for plain-text logging and CI/CD pipelines). |
| **`--color`** | Forces ANSI color output regardless of environment defaults. |
---
## ๐ ๏ธ Stack Auto-Detection Matrix
Limitless automatically detects your project stack by probing workspace manifests in priority order:
| 1 | **Node.js** | `package.json`, `pnpm-lock.yaml`, `yarn.lock` | `pnpm dev` / `yarn dev` / `npm run dev` |
| 2 | **Python** | `requirements.txt`, `manage.py`, `main.py`, `app.py` | `python manage.py runserver` / `uvicorn main:app` / `python app.py` |
| 3 | **Rust** | `Cargo.toml` | `cargo run` |
| 4 | **Go** | `go.mod` | `go run .` |
| 5 | **Java** | `build.gradle`, `pom.xml` | `./gradlew bootRun` / `mvn spring-boot:run` |
| 6 | **Docker** | `Dockerfile`, `docker-compose.yml` | Secondary stack audit & port verification |
---
## ๐ Gamification & Badges
As you run diagnostics and repair your workspace, Limitless awards persistent developer badges saved locally to `~/.limitless/`:
* ๐ก๏ธ **Port Whisperer:** Successfully freed a blocked port holding up your server.
* โก **Env Master:** Fixed or generated missing `.env` configurations.
* ๐น๏ธ **Arcade Champion:** Achieved a top-5 high score in SyntaxBreaker Arcade.
* ๐ฆ **Night Owl:** Executed diagnostics between 1:00 AM and 4:00 AM.
* ๐ **Speed Runner:** Achieved a 100% environment health score on the first scan.
---
## โ๏ธ Configuration (`~/.limitless/config.json`)
Customize Limitless behavior globally by modifying `~/.limitless/config.json`:
```json
{
"preferred_stack": null,
"auto_approve_safe_fixes": false,
"color_enabled": true,
"animation_enabled": true,
"verbose_mode": false
}
```
---
## ๐ Complete Documentation Index
| ๐ฅ **[INSTALLATION.md](docs/INSTALLATION.md)** | Step-by-step setup for Windows, macOS, Ubuntu/Debian, and Homebrew. |
| ๐ก **[USAGE.md](docs/USAGE.md)** | Full command reference, flag combinations, and CLI usage patterns. |
| ๐๏ธ **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** | Technical deep-dive into async Tokio runtime, diagnostic engine, and TUI renderer. |
| ๐ค **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** | Guidelines for adding new stack detectors, checks, and arcade snippets. |
| โ **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** | FAQ covering elevated OS permissions, broken PATH entries, and port conflicts. |
---
## ๐งช Development & Testing
```bash
# Run unit & integration test suite
cargo test
# Run strict linter checks
cargo clippy --all-targets -- -D warnings
# Build release artifact
cargo build --release
```
---
## ๐ License
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for full details.