English | 中文文档

Ask CLI

A powerful command-line assistant that converts natural language into executable commands using AI. Features multiple model management, intelligent switching, and comprehensive safety checks.

🔗 Repository

GitHub: https://github.com/zhump/ask2-ai-cli

✨ Key Features

🎯 Shell Integration

• askx helper function for seamless shell history integration
• One-command installation with automatic shell detection
• Press Enter to execute with streamlined confirmation
• Color-coded command display for better readability
• Automatic cleanup and easy uninstallation

🎯 Multiple AI Model Support

• Configure multiple AI models with different settings (temperature, API endpoints)
• Easy switching between models with simple commands
• Smart model management with visual status indicators
• Automatic upgrade from single-model to multi-model configurations

🛡️ Advanced Safety

• Dangerous command detection with double confirmation
• Privilege escalation warnings and suggestions
• Interactive confirmation before command execution
• Command explanations for educational purposes

💻 Developer-Friendly

• Debug mode with detailed timing and prompt visibility
• Command history with execution tracking
• Cross-platform support (macOS, Linux, Windows, WSL)
• Smart environment detection (shells, package managers, project types)

🚀 Installation

npm install ask2-ai-cli -g

⚙️ Configuration

Initial Setup

ask config

This shows your configuration file path. Edit the file to add your API configuration:

Configuration Format

{
  "models": [
    {
      "name": "moonshotai/kimi-k2:free",
      "apiKey": "your-api-key-here",
      "apiUrl": "https://openrouter.ai/api/v1/chat/completions",
      "model": "moonshotai/kimi-k2:free",
      "temperature": 0.3,
      "enabled": true
    },
    {
      "name": "glm-4.5",
      "apiKey": "your-api-key-here",
      "apiUrl": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
      "model": "glm-4.5",
      "temperature": 0.3,
      "enabled": false
    }
  ]
}

Recommend using openrouter's free model API and your internal model API to avoid information leakage and enhance security.

Test Your Setup

ask test

📖 Usage

Shell Integration (Recommended)

For the best experience with shell history support, install the askx helper function:

# Install askx function to your shell
ask install

# Reload your shell configuration
source ~/.zshrc    # or ~/.bashrc for bash users

# Use askx for commands with history support
askx "list all files"
askx "kill process on port 3000"
askx "find large files over 100MB"

askx Benefits:

• ✅ Commands are added to your shell history
• ✅ Use arrow keys to find previously executed commands
• ✅ Streamlined confirmation: just press Enter to execute
• ✅ Color-coded command display for better readability

Example askx workflow:

$ askx "delete files older than 30 days"

Execute this command? (Enter/n): find . -type f -mtime +30 -delete 
[Press Enter]
✅ Command executed successfully and added to history

Uninstall askx:

ask uninstall      # Remove askx function
source ~/.zshrc    # Reload shell

Basic Commands

# Traditional interactive mode
ask list all files
ask find large files over 100MB
ask kill process on port 3000

# Model management
ask ls                     # List all models
ask use qwen3    # Switch models
ask config                 # View configuration

# Advanced options
ask --debug complex query       # Debug mode
ask --explain rm -rf folder     # Get explanations
ask --print "your query"        # Print command only (used by askx)

Model Management Workflow

1. List Available Models

ask ls

📋 Available Models
──────────────────────────────────────────────────
✅ GLM-4.5 Main
   Model: glm-4.5 | Temperature: 0.3 | API: open.bigmodel.cn
⚪ Creative Mode  
   Model: glm-4.5 | Temperature: 0.8 | API: open.bigmodel.cn
──────────────────────────────────────────────────
🎯 Current: GLM-4.5 Main

2. Switch Models

ask use qwen3

✅ Successfully switched to model 'Creative Mode'

📋 Active model details:
──────────────────────────────
  Name: Creative Mode
  Model: qwen3
  Temperature: 0.3

Interactive Command Flow

When Ask generates a command, you can:

• Enter → Execute immediately
• N → Cancel and exit
• C → Generate different solution
• E → Get detailed explanation

$ ask check disk space

Suggested command:
df -h

⚠️  Please review the command carefully before execution!

Choose action:
  Enter - Execute command
  N - Exit
  C - Change answer
  E - Explain command

Please choose (Enter/N/C/E): [E]

📚 Command Explanation
──────────────────────────────────────────────────
Command: df -h

Explanation:
• df: Display filesystem disk space usage
• -h: Human-readable format (KB, MB, GB instead of bytes)
• Shows available space, used space, and mount points
• Safe read-only operation with no system changes

🔧 Command Reference

Command	Description	Example
ask [query]	Convert natural language to commands	ask install docker
askx [query]	Execute with shell history support	askx "list all files"
ask install	Install askx helper function	ask install
ask uninstall	Remove askx helper function	ask uninstall
ask ls	List all model configurations	ask ls
ask use <name>	Switch to specific model	ask use "Creative Mode"
ask config	Show configuration file path and content	ask config
ask test	Test AI connectivity	ask test --debug
ask log	View command history	ask log --limit 10

Command Options

Global Options:

• --debug, -d → Enable debug mode with timing info
• --explain, -e → Get command explanations
• --print, -p → Print command only (used internally by askx)

Log Options:

• --clear → Clear command history
• --limit <n> → Show last N entries

🛡️ Safety Features

Dangerous Command Protection

$ ask "delete all files in current directory"

⚠️  DANGEROUS OPERATION DETECTED!
This command may cause irreversible damage to your system:
rm -rf *

Are you absolutely sure you want to execute this command?

Press Enter to confirm explicitly (anything else will cancel): [Cancel]

✅ Operation cancelled for safety.

Privilege Escalation Detection

$ ask "install nginx"

Suggested command:
apt install nginx

⚠️  This command may require elevated privileges.
Consider using: sudo apt install nginx

🌍 System Support

Operating Systems: macOS, Linux, Windows, WSL
Package Managers: brew, apt, yum, dnf, pacman, winget, choco
Project Types: Node.js, Python, Java, Go, Rust, Git repositories
Shells: bash, zsh, fish, PowerShell, cmd

📝 License

MIT