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 Forever: No subscription, no credit card, no hidden costs
• Unlimited Usage: No daily limits, no restrictions, use as much as you need
• No API Key Required: Works out of the box with public NVIDIA Builds access
• 9 AI Models: Access all supported models including Qwen 3.5, Mistral, Llama, Gemma, GLM, DeepSeek, GPT-OSS, and StepFun
• Token Restoration: Simply close and reopen the CLI to reset your token count — start fresh anytime!

💡 Tip: If you reach the token limit for a model, just close the CLI (/quit) and reopen it (luxyie chat) to restore all tokens. Your conversation history is saved automatically!

🤖 AI Agent Tools (8 Tools)

🔒 Security First: Every tool requires explicit user approval with "Allow once / Always allow / Deny" options.

✅ 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 API
• ⚡ 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
• 📊 Token Usage Tracking — Visual progress bars and warnings
• 🔧 Git Integration — Status, log, diff, and AI-assisted commits
• 🔄 Auto-Update — Checks for updates on startup and every 5 minutes

💬 Chat Commands

Inside a chat session, use these commands:

Model Commands

Example /models output:

🤖 Available Models
──────────────────────────────────────────────────────────────────────

  ● qwen/qwen3.5-397b-a17b [thinking] [axios]
    temp: 0.6 | max_tokens: 16384 | top_p: 0.95

  ○ mistralai/mistral-small-4-119b-2603 [thinking] [axios]
    temp: 0.1 | max_tokens: 16384 | top_p: 1.0
  ...

Use /model select to switch models interactively

Git Commands

🤖 Available Models

Luxyie supports 9 advanced AI models via NVIDIA Builds:

💡 Tip: Models marked with ✅ support extended reasoning for complex problem-solving. Use /models to see full details including provider and parameters.

📊 Token Management

Luxyie CLI tracks token usage automatically and provides:

• Visual progress bars showing current usage vs. model limit
• Warnings at 80% usage so you can plan accordingly
• Interactive options when limit is reached:
  • 💾 Save session and restart
  • 🔄 Switch to another model
  • 🚪 Exit the CLI
• Easy Token Restoration: Close and reopen the CLI to reset your token count — your history is saved automatically!

Example /stats output:

📊 Session Statistics
──────────────────────────────────────────────────
  Duration: 5m 30s
  Tokens: ████████████████░░░░ 12,450 / 16,384 tokens (76%)
  Model: qwen/qwen3.5-397b-a17b
──────────────────────────────────────────────────

🛠️ 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

# 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

# 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"

Git integration

luxyie chat
/git status
/git ai-commit

Switch models

# List all models
/models

# Open interactive selection
/model select

🔒 Security

• 🔐 Tool Approval: Every tool execution requires user consent (Allow once / Always allow / Deny)
• 🛡️ 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   # Main chat loop
│   ├── ask.command.ts    # Quick questions
│   ├── config.command.ts # Configuration management
│   ├── history.command.ts# Session management
│   ├── model.command.ts  # Model listing & selection
│   ├── token-limit.command.ts # Token management
│   └── ...
├── services/             # Business logic
│   ├── config.service.ts # Configuration manager
│   ├── llm.service.ts    # API client (OpenAI + Axios)
│   ├── history.service.ts# Session persistence
│   ├── update.service.ts # Auto-update checker
│   └── models.ts         # 9 available models
├── tools/                # Agent tools
│   └── executor.ts       # 8 tool implementations
├── ui/                   # Terminal UI
│   ├── components.ts     # Visual components
│   ├── renderer.ts       # Markdown rendering
│   └── terminal.ts       # Input handling
├── utils/                # Modular utilities
│   ├── git.ts            # Git operations
│   ├── paste-detector.ts # Paste detection
│   ├── session-manager.ts# Session lifecycle
│   ├── tool-executor.ts  # Tool execution flow
│   └── 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