limitless-cli 1.0.0

A beginner-friendly environment diagnostic tool
Documentation

๐Ÿ’ก 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.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ ๐Ÿš€ 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:

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ ๐ŸŒŒ 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.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ โš”๏ธ SYNTAXBREAKER ARCADE GAME                             โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ Type the code snippet:                                   โ”‚
โ”‚ function hello() { }                                     โ”‚
โ”‚                                                          โ”‚
โ”‚ Your input: function hello()_                            โ”‚
โ”‚                                                          โ”‚
โ”‚ Score: 120  |  Time: 45s  |  WPM: 64                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

โšก Installation

Option A: Via Cargo (Recommended)

# Build and install globally from source
cargo install --path .

# Or install directly from Crates.io
cargo install limitless-cli

Option B: Build from Source

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.


๐Ÿ“– Command Cheatsheet

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

Flag Description
--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:

Priority Stack Project Markers Auto-Launched Dev Command (limit dev)
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:

{
  "preferred_stack": null,
  "auto_approve_safe_fixes": false,
  "color_enabled": true,
  "animation_enabled": true,
  "verbose_mode": false
}

๐Ÿ“š Complete Documentation Index

Document Description
๐Ÿ“ฅ INSTALLATION.md Step-by-step setup for Windows, macOS, Ubuntu/Debian, and Homebrew.
๐Ÿ’ก USAGE.md Full command reference, flag combinations, and CLI usage patterns.
๐Ÿ—๏ธ ARCHITECTURE.md Technical deep-dive into async Tokio runtime, diagnostic engine, and TUI renderer.
๐Ÿค CONTRIBUTING.md Guidelines for adding new stack detectors, checks, and arcade snippets.
โ“ TROUBLESHOOTING.md FAQ covering elevated OS permissions, broken PATH entries, and port conflicts.

๐Ÿงช Development & Testing

# 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 for full details.