@nexabot/nexa-cli

◈ Nexa CLI

One CLI. Any AI Model.

Nexa CLI is a world-class, premium Terminal User Interface (TUI) for a next-generation universal AI coding assistant. It features a modern, developer-first aesthetic inspired by Cursor, Warp, and Vercel.

With Bring Your Own Key (BYOK) support and seamless provider integration, Nexa CLI provides a high-fidelity interface to interact with Gemini, OpenAI, Claude, OpenRouter, and local Ollama models.

---

Design Theme & Colors

Nexa CLI features a curated, high-contrast dark theme optimized for terminal readability:

• Primary Blue (#2563EB) — Structural borders, key headers, and focus highlights
• Accent Cyan (#06B6D4) — Active selections, prompts, and highlight states
• Success Green (#22C55E) — Successful operations, file saves, and checklist checkmarks
• Warning Amber (#F59E0B) — Toggles and notification warnings
• Error Crimson (#EF4444) — Failure markers and validation errors

---

Features

• Slash Commands (/): Type / inside the prompt box to trigger an autocomplete popup selection for modes, actions, and settings.
• Interactive Connect (/connect): A consecutive three-stage setup sequence (Select Provider ➔ Enter API Key ➔ Select Active Model) to hook up your services instantly.
• Command Palette (Ctrl+P / /commands): Search and execute commands like Explain Code, Fix Bugs, Generate Commit, and Review PR on the fly.
• Settings Menu (Ctrl+, / /settings): Interactive forms to update API Keys, toggle Agent auto-execution rules, and switch themes.
• Responsive Layout: Adjusts margins, columns, and layout rules dynamically based on your terminal's window size.
• Markdown & Syntax Highlight: A built-in high-performance regex-based parser that handles headers, lists, markdown tables, code syntax highlighting (TypeScript, Python, etc.), and side-by-side git diff styling.
• Permission-Based Tool Execution: Securely run terminal commands, write/modify local files, and list directories using a sandboxed agent loop.
• Security Confirmation Dialogue: Prompts a double-bordered Warning Overlay before executing any commands or editing files. Supports [ Allow Once ], [ Always Allow for Workspace ], and [ Deny ]. Safe read operations (like cat, ls, git diff) run automatically.
• Build Plan Review: When a plan is proposed by the agent, it renders a list checklist card detailing the proposed actions and estimated time, asking the user to confirm before proceeding.
• Agent Mode (Tab / /agents): Shows a dynamic, live progress indicator representing the agent's current task (Planning, Reading project, Editing files, Running build, Running tests).

---

Navigation & Shortcuts

Action / Shortcut	Description
/	Slash Menu — Type / to select actions, change models, or configure keys
Tab	Switch Mode — Toggle between Build (Chat) and Plan (Agent) modes
Ctrl+P	Command Palette — Search and run TUI operations
Ctrl+K	Models Menu — Quick model selector
Ctrl+,	Settings Menu — Configure key masks and theme variables
Ctrl+L	Clear Chat — Clear the history buffer
Esc	Close Overlay — Cancel connection stages or overlays
Enter	Submit — Confirm prompt typing or menu selection
↑ / ↓	Navigate — Scroll lists, models, and command items

---

Setup & Running

Installation

You can install Nexa CLI globally directly from NPM:

npm install -g @nexabot/nexa-cli

how to run it

nexa

Configuration Paths

Nexa CLI securely stores your API keys and default models in the standard configuration directory for your platform:

• Linux: ~/.config/nexa/config.json
• macOS: ~/Library/Application Support/Nexa/config.json
• Windows: %APPDATA%/Nexa/config.json

---

CLI Commands & Subcommands

Run nexa directly from your terminal to launch the interactive TUI, or use any of the dedicated subcommands below:

Command	Action
nexa	Launch the main interactive chat and agent TUI
nexa login / nexa provider	Start the interactive setup wizard to configure a provider, submit key, and fetch models
nexa models	Fetch available models for your active provider and change default model
nexa config	View your active configuration path, current provider, model, and masked keys
nexa doctor	Perform connection diagnostics, check credential validity, and list status
nexa update	Check for updates and update Nexa CLI to the latest version
nexa logout	Remove saved configuration and clear keys

---

Local Development Setup

If you want to contribute or run the development server locally:

Prerequisites

• Node.js (v18.0.0 or higher)
• npm

Local Setup

1. Clone or navigate to the workspace:

   cd nexa-cli

2. Install dependencies:

   npm install

Running Local Commands

To run in development mode:

npm run dev

To build and compile TypeScript files to production JavaScript:

npm run build

To run your compiled local build:

node dist/index.js