An intelligent, terminal-first AI assistant powered by NVIDIA Builds.

🚀 Installation

Quick Install

npm install -g luxyie.ai-cli

After installation, the luxyie command is available globally:

luxyie chat

💡 Auto-configuration: The post-install script automatically sets up permissions. If the command isn't recognized, restart your terminal.

Platform-Specific Setup

⚙️ Configuration

Luxyie CLI uses NVIDIA Builds public access API key out of the box — no configuration needed.

Using Your Own API Key

# Linux/macOS
export NVIDIA_API_KEY="your-api-key-here"

# Windows (PowerShell)
$env:NVIDIA_API_KEY="your-api-key-here"

Interactive Configuration

luxyie config set    # Edit settings interactively
luxyie config show   # View current configuration
luxyie config reset  # Reset to defaults

Configuration is stored in ~/.luxyie/config.json.

📱 Android (Termux)

Luxyie AI CLI is fully compatible with Termux on Android.

Quick Install

# 1. Install dependencies
pkg update && pkg upgrade
pkg install nodejs-lts chromium

# 2. Install Luxyie (auto-configures permissions)
npm install -g luxyie.ai-cli

# 3. Verify
luxyie --version

Troubleshooting

Permission errors?

# Auto-fix
node /data/data/com.termux/files/usr/lib/node_modules/luxyie.ai-cli/scripts/fix-termux-permissions.cjs

# Or manual
npm install -g luxyie.ai-cli --ignore-scripts
chmod +x $(which luxyie)

Web features not working?

pkg install chromium
termux-setup-storage

Termux Feature Support

See docs/TERMUX-GUIDE.md for complete documentation.

🔧 Features

✨ Unlimited & Free

• 100% Free: No subscription required
• Unlimited Usage: No token limits
• No API Key Required: Works out of the box
• 8 AI Models: Access all supported NVIDIA models including Mistral, Llama, Gemma, Qwen, DeepSeek, and more

🤖 AI Agent Tools (8 Tools)

🔒 Security First: Every tool requires explicit user approval.

✅ Core Capabilities

• 💬 Natural Language Coding — Write, debug, and explain code
• 🔍 Web Search & Research — Real-time results from DuckDuckGo
• 📄 File Analysis — Read and summarize any file type
• 🖼️ Multimodal Input — Analyze images via NVIDIA Vision
• ⚡ Terminal Automation — Safe command execution
• 💾 Persistent Context — Save and resume conversations
• 🌐 Multi-Language — Auto-detects and responds in your language
• 🧠 Reasoning Mode — Extended thinking for complex problems

💬 Chat Commands

Inside a chat session, use these commands:

Model Selection Menu

Type /model select or /models to open an interactive menu where you can browse and select from all available AI models:

• ✅ Visual indicator of current model
• ✅ Temperature and capabilities shown
• ✅ Reasoning support tags
• ✅ Cancel option to exit without changing

🤖 Available Models

Luxyie supports 8 advanced AI models via NVIDIA Builds:

💡 Tip: Models marked with ✅ support extended reasoning for complex problem-solving.

🛠️ CLI Commands

# Start interactive chat
luxyie chat                  # or: luxyie c

# Ask a quick question
luxyie ask "What is TypeScript?"

# Manage configuration
luxyie config show           # View settings
luxyie config set            # Edit interactively
luxyie config reset          # Reset to defaults
luxyie config model          # Model information

# Manage history
luxyie history list          # List all sessions
luxyie history show <id>     # View a session
luxyie history resume <id>   # Resume a session
luxyie history export <id>   # Export to JSON/MD/TXT
luxyie history delete <id>   # Delete a session
luxyie history clear         # Clear all sessions

# Check for updates
luxyie update check          # Check for updates
luxyie update install        # Install latest version
luxyie update status         # Show version info

# List models
luxyie models                # List all available models

# Help
luxyie --help                # Show help
luxyie --version             # Show version

💬 Quick Examples

Start a chat

luxyie chat
> Explain quantum computing in simple terms

Generate code

luxyie ask "Write a Node.js script that downloads a webpage"

Analyze a file

luxyie ask "Summarize this file: ./src/core/agent.ts"

Analyze an image

luxyie ask "Describe this image: ./screenshot.png"

Run commands safely

luxyie chat
> List all files and show only .js files

Switch models

# Interactive menu
/model select

# Direct switch
/model mistralai/mistral-small-4-119b-2603

🔒 Security

• 🔐 Tool Approval: Every tool execution requires user consent
• 🛡️ Sandboxed Commands: Commands run in current directory only
• 🔍 Symlink Protection: Directory traversal is blocked
• ⚡ Timeout Protection: Operations have configurable timeouts
• 📝 Audit Trail: All tool executions are logged in history

📦 For Developers

Build from Source

git clone https://github.com/shindozk/luxyie.ai-cli.git
cd luxyie.ai-cli
npm install
npm run build
npm link

Available Scripts

Project Structure

src/
├── cli/                  # CLI setup (Commander.js)
├── commands/             # Command handlers
│   ├── chat.command.ts   # Chat loop (12+ internal commands)
│   ├── ask.command.ts    # Quick questions
│   ├── config.command.ts # Configuration management
│   ├── history.command.ts# Session management
│   └── ...
├── services/             # Business logic
│   ├── config.service.ts # Configuration manager
│   ├── llm.service.ts    # API client (OpenAI + Axios)
│   ├── history.service.ts# Session persistence
│   └── models.ts         # 8 available models
├── tools/                # Agent tools
│   └── executor.ts       # 8 tool implementations
├── ui/                   # Terminal UI
│   ├── components.ts     # Visual components
│   ├── renderer.ts       # Markdown rendering (marked + marked-terminal)
│   ├── terminal.ts       # Input handling
│   └── spinner.ts        # Loading indicators
├── utils/                # Modular utility functions
│   ├── abort-handler.ts  # ESC/Ctrl+C handling
│   ├── paste-detector.ts # Paste detection
│   ├── session-manager.ts# Session lifecycle
│   ├── tool-executor.ts  # Tool execution flow
│   ├── stream-processor.ts# Stream accumulation
│   ├── terminal-input.ts # Terminal input handling
│   └── message-formatter.ts# Message formatting
├── prompts/              # System prompts
│   └── system-prompt.ts  # Agent identity & rules
└── types/                # TypeScript definitions

Running Tests

npm test                   # Run all tests
npm test -- --coverage     # With coverage report
npm test -- --watch        # Watch mode

Test Coverage: 40 tests passing across 3 suites (UI helpers, validation, format).

⌨️ Shortcuts

🏗️ Architecture

User Input
    ↓
TerminalUI (readline + paste detection)
    ↓
ChatCommand / AskCommand
    ↓
APIClient (OpenAI SDK or Axios provider)
    ↓
NVIDIA Builds API
    ↓
StreamAccumulator (content + reasoning + tool calls)
    ↓
ToolExecutor (8 tools with approval)
    ↓
HistoryManager (session persistence)
    ↓
Renderer (Markdown → Terminal)
    ↓
User Output

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• TypeScript strict mode
• Prettier for formatting
• ESLint for linting
• Jest for testing

📄 License

This project is licensed under the MIT License — see the LICENSE file.

🙏 Acknowledgments

• NVIDIA — For the AI models and API
• Commander.js — CLI framework
• esbuild — Blazing fast bundler
• Puppeteer — Browser automation
• marked — Markdown parser
• Inquirer — Interactive prompts