The autonomous AI software engineer in your terminal.
Build, analyze, debug, and architect multi-file projects directly from your command line. Equipped with persistent PostgreSQL memory and 7 live developer tools.
Zero configuration • No API key needed • Connects to cloud automatically
Up & Running in 3 Simple Steps
Everything you need to know to get Lumina CLI working on your machine in under 60 seconds.
Install Globally via npm
Open your terminal on macOS, Linux, or Windows and install Lumina CLI globally:
Sign In with GitHub (RFC 8628)
Run 'lumina login'. It displays a code and opens your browser for one-click GitHub authorization.
Launch Interactive Companion
Run 'lumina wakeup' to open the interactive capability selector (Chat, Tools, or Agent).
- •Copying and pasting code between browser windows and text editors continuously
- •Manually creating folders and copy-pasting 10 separate files
- •AI hallucinating outdated APIs without live documentation inspection
- •Losing conversational memory the moment you close your browser tab
- ✔Lives right in your terminal alongside your active project workspace
- ✔Autonomous Agent scaffolds entire multi-file project directories to disk
- ✔Live Google search and code execution verify solutions in real time
- ✔Neon PostgreSQL database persists multi-turn history seamlessly
Lumina Architecture in Simple Terms
Key concepts made clear for both beginners and experienced engineers.
Zero Manual API Keys
You never have to register, generate, or paste API keys manually. Lumina CLI uses built-in cloud AI inference right out of the box with zero setup.
RFC 8628 Device Flow
The standard protocol used by tools like GitHub CLI and Netflix. The terminal shows a one-time code and lets you approve it in your normal browser window.
Autonomous Full-Stack Agent
Instead of just printing code on screen, Agent Mode designs the architecture, creates the folder hierarchy, and writes actual source files directly onto your disk.
Local Tool Sandboxing
When Lumina inspects Git status, reads project files, or tests Python/JS snippets, it runs them safely on your local machine with strict sandboxing.
Built for Modern Engineering Velocity
Everything you need in an AI software engineering companion — without browser context-switching or hallucinated guesses.
Persistent Conversational Memory
Multi-turn AI reasoning where every session, title, role, and message is persisted to Neon PostgreSQL via Prisma ORM and automatically restored.
Real-Time Tool Calling Suite
Live Google search, sandboxed Python/Node.js runner, math formula engine, git repository inspector, and workspace file reader.
Autonomous Project Architect
Scaffolds complete multi-file projects with disk directory creation, un-truncated file writes, and copyable launch commands.
RFC 8628 Device Authorization
Enterprise-grade headless terminal login approved through the Next.js web portal via GitHub OAuth 2.0 with polling backoff.
Resilient Multi-Model Pipeline
Powered by Groq's high-speed LPU inference engine (openai/gpt-oss-120b) with automatic fallback (openai/gpt-oss-20b) on 429 rate limits.
Bespoke Cyberpunk TUI Design
Curated semantic ANSI palettes, glow badges, custom marked terminal markdown parser, and smart table-to-bullet-list converter.
Engineered for Every Engineering Task
Switch effortlessly between persistent conversational reasoning, real-time developer tool execution, and autonomous multi-file application scaffolding.
💬 Chat Mode
Interactive multi-turn conversational AI pair programmer. Restores previous session context seamlessly from Neon PostgreSQL.
/clear, exit⚡ Tool Calling Mode
Arms the LLM with live Internet access, sandboxed code execution, workspace file inspection, and git diagnostics.
🤖 Autonomous Agent
Generates production-grade multi-file applications from a single prompt and automatically creates directory trees on your disk.
Experience Lumina in Action
Click any mode below to test real terminal flows, or type commands directly into the prompt.
lumina login, lumina whoami, mode agent, or helpai + Groq LPU7 Real-Time Tools at Lumina's Disposal
Lumina doesn't guess or hallucinate. It executes live tools directly, capturing stdout and synthesizing natural language answers.
Searches the live web for technical documentation, new framework releases, and error solutions.
Safely executes JavaScript (Node.js) or Python code in an isolated subprocess to test algorithms.
Evaluates mathematical equations, algebraic operations, trigonometry, and logarithms with high precision.
Reads project source files, configuration files, and package.json to analyze dependencies and code.
Inspects uncommitted diffs, active branches, commit logs, and repository health.
Fetches live JSON data or raw content from any public HTTP/HTTPS endpoint.
Inspects local developer OS architecture, Node.js runtime version, memory usage, and platform specs.
Web & Google Search
Active Tool Sandbox & Execution Trace
Production Cloud Topology & Workflows
Clean separation between local client execution and cloud infrastructure on Vercel, Render, Neon, and Groq.
Client vs Production Cloud Infrastructure
End users need zero configuration. The CLI seamlessly coordinates with Lumina Cloud.
https://luminacli.vercel.app
Device code authorization, approval pages, and social login handler.
https://lumina-cli.onrender.com
Better Auth device plugin, GitHub OAuth provider, and message persistence.
Get Started with Lumina
Zero-config quickstart for users, or run the complete full-stack monorepo locally.
Global Install
Install the CLI globally to enable the lumina command in any terminal.
npm install -g @piyushkumariiitj/lumina-cli@latest # Or instant run: npx @piyushkumariiitj/lumina-cli@latest wakeup
Authenticate
Get a one-time code and login via GitHub OAuth browser portal.
lumina login
Launch Agent
Start interactive console for Chat, Tools, and Scaffolding.
lumina wakeup
CLI Command Reference
Complete options and flag reference matching Commander.js definitions.
| Command | Options | Category | Description | Action |
|---|---|---|---|---|
lumina wakeup | — | Interactive | Launch interactive menu to choose between Chat, Tools, Autonomous Agent, or Diagnostics. | |
lumina login | --server-url <url>, --client-id <id> | Auth | Authenticate with GitHub via browser device approval (RFC 8628). Optionally specify custom backend server URL. | |
lumina whoami | --server-url <url> | Diagnostics | View current authenticated developer profile, user ID, active Groq model, and database status. | |
lumina logout | — | Auth | End session and securely clear stored local credentials from ~/.better-auth/token.json. | |
lumina --help | -h | Utility | Display CLI help menu, available commands, and option flags. | |
lumina --version | -v | Utility | Output currently installed version of Lumina CLI (e.g. v1.0.5). | |
/clear | — | In-Chat | Clear the terminal screen inside Chat/Tools mode while preserving PostgreSQL memory. | |
exit / quit | — | In-Chat | Gracefully end the interactive conversational AI or agent session. |
Troubleshooting & Solved Edge Cases
Hardened for zero-crash execution across any machine and network condition.
Commander.js options with complex defaults previously passed unexpected object constructors when options like --server-url were omitted.
Configured clean option flags with explicit fallback resolution in src/lib/server-url.js, ensuring safe defaults whether running in production or locally.
Frequently Asked Questions
Everything a beginner needs to know to get started with Lumina CLI smoothly.
Lumina is an AI-powered coding companion that lives directly in your computer's terminal. Instead of copying and pasting code between a web browser and your editor, you can chat with AI, search docs, run Python/JS code snippets, and even scaffold full multi-file web applications directly from your command line.
Ready for your first run?
Open any terminal window and run npx @piyushkumariiitj/lumina-cli@latest wakeup