CLI AI

Natural language to shell commands. Multi-provider AI support.

Describe what you want in plain English. Get the right command. Review, execute or copy.

Supports Anthropic, OpenAI and OpenRouter providers.

Features

• Multi-provider - Anthropic, OpenAI, OpenRouter with any model support
• Natural language - Just describe what you want to do
• Cross-platform - Windows (PowerShell, CMD, Git Bash), macOS, Linux
• Shell-aware - Commands tailored to your detected shell
• Interactive - Execute, copy, edit or request alternatives
• Context-aware - Remembers your conversation history for smarter suggestions
• Secure - API keys stored in system keyring, never in plain text
• Risk assessment - Color-coded safety levels for every command

Quick Start

# Install globally
npm install -g @fmdzc/cli-ai

# Run
s
# or
cli-ai

On first run, you'll be prompted for an API key. Get one from:

• Anthropic
• OpenAI
• OpenRouter

Usage

Type what you want in natural language:

> find files larger than 100MB

$ find . -size +100M -type f
Risk: low

[1] Execute  [2] Copy  [3] Edit  [4] Alternatives  [5] Cancel

Slash Commands

Type / to access commands:

Command	Description
/config	Open settings panel
/help	Show help and shortcuts
/clear	Clear command history
/exit	Exit application

Keyboard Shortcuts

Input Mode

Key	Action
/	Open command palette
Enter	Submit query
O	Toggle output expansion
Ctrl+D	Exit (when empty)

Command Proposal

Key	Action
1 / Enter	Execute command
2	Copy to clipboard
3	Edit command
4	Show alternatives
5 / Esc	Cancel
?	Explain command

Settings Panel

Key	Action
Tab	Next section
Up/Down	Navigate items
Enter	Toggle/Select
Esc	Close

Settings

Access settings with /config:

Provider & Model

Supported AI providers:

• Anthropic - Claude models
• OpenAI - GPT models
• OpenRouter - 100+ models from various providers

Any model from your selected provider is supported. Use the built-in presets or enter a custom model ID.

API Keys

Manage API keys for each provider separately:

• View key status (✓ Configured / ✗ Not set)
• Add or change keys for any provider
• Keys are stored securely per provider

Options

Setting	Description
Context	Pass conversation history to AI for smarter suggestions
Show explanations	Display command explanations
Syntax highlighting	Colorize command output
Simple mode	Minimal UI mode

Risk Assessment

Level	Color	Meaning
Low	Green	Safe, read-only commands
Medium	Yellow	Modifies files or system state
High	Red	Potentially destructive

Security

API Key Storage

Your API keys are stored securely using industry-standard methods. Each provider's key is stored separately.

Primary: System Keyring

Platform	Storage Backend
macOS	Keychain
Windows	Credential Manager
Linux	Secret Service API (GNOME Keyring, KWallet)

The system keyring provides OS-level encryption and access control. API keys are never stored in plain text or environment variables.

Fallback: Encrypted File

If the system keyring is unavailable, keys are stored in an encrypted file at ~/.cli_ai_assistant/. The encryption key is derived from your machine's unique identifiers (hostname + username), making the encrypted file non-portable and machine-specific.

Key Management

• View: See masked keys and storage method per provider in /config
• Add: Configure API keys for Anthropic, OpenAI or OpenRouter
• Change: Update any API key anytime through settings
• Status: Green ✓ indicates configured, red ✗ indicates not set

Requirements

• Node.js 20+
• Build tools for native modules:

Platform	Command
Windows	npm install -g windows-build-tools (Admin)
macOS	xcode-select --install
Ubuntu/Debian	sudo apt install build-essential libsecret-1-dev
Fedora	sudo dnf install gcc-c++ libsecret-devel
Arch	sudo pacman -S base-devel libsecret

Development

git clone https://github.com/fmdz387/cli-ai.git
cd cli-ai
pnpm install
pnpm dev        # Watch mode
pnpm build      # Production build

License

ISC