AI CLI

A command-line tool that generates shell commands from natural language descriptions using OpenAI's API.

Features

• 🤖 Natural language to shell command conversion
• 🛡️ Safety-first approach with read-only preferences
• 📊 Verbose mode with detailed API response information
• 🎯 One suggestion at a time: confirm, retry, or abort with a single keypress
• 🔧 Cross-platform support (Linux, macOS, windows etc)

Installation

Prerequisites

• Go 1.26 or later
• OpenAI API token

Option 1: Install with go install (Recommended)

go install github.com/brainexe/ai@latest

Option 2: Build from Source

# Clone the repository
git clone https://github.com/brainexe/ai.git
cd ai-cli

make build

Setup

1. Set your OpenAI API token:

export OPENAI_TOKEN="your-openai-token-here"

Usage

The tool suggests exactly one command and waits for a single keypress:

• Enter — execute the command
• Esc — reject it and fetch a new suggestion (rejected commands are not suggested again)
• Ctrl-C — abort without executing anything

Examples

ai "find biggest file here"
find . -type f -exec ls -la {} + | sort -k5 -nr | head -1
[Enter] run   [Esc] retry   [Ctrl-C] abort

ai "search for TODO in all files"
grep -rn "TODO" .
[Enter] run   [Esc] retry   [Ctrl-C] abort

ai "show files modified in last 24 hours"
find . -type f -mtime -1
[Enter] run   [Esc] retry   [Ctrl-C] abort

ai bpftrace trace all page faults, show pid, application name
sudo bpftrace -e 'tracepoint:exceptions:page_fault_user { printf("%d %s\n", pid, comm); }'
[Enter] run   [Esc] retry   [Ctrl-C] abort

Command Options

Verbose Mode

Use the -v flag to see detailed information about the API call and generated command:

ai -v "show disk usage"

Verbose mode displays:

• API request timing information
• Raw API response (pretty-printed JSON)

Safety Features

• Read-only preference: Prioritizes non-destructive commands
• Destructive action warnings: Avoids rm -rf, chmod -R, sudo unless explicitly requested
• Single command output: Ensures only one safe command per response
• Explicit confirmation: Nothing runs until you press Enter
• Path safety: Properly quotes paths containing spaces
• Command sanitization: Removes code blocks and extra formatting

Development

Build Commands

# build the "ai" binary
make build

# Run linter
make lint

Examples

# File operations
ai "show files modified in last 24 hours"
ai "count lines in all go files"

# System information
ai "show memory usage"
ai "list running processes"

# Text processing
ai "find all TODO comments in source code"
ai "replace tabs with spaces in all files"

# Network operations
ai "check if port 8080 is open"
ai "show network connections"

Configuration

The tool uses the following environment variables:

• OPENAI_TOKEN: Your OpenAI API token in env vars (required)

License

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

Common Issues

"OPENAI_TOKEN not set" error

• Ensure you've exported your OpenAI API token as an environment variable

"No command generated" error

• Try rephrasing your request more clearly
• Check your internet connection
• Verify your OpenAI API token is valid

Command not found

• Make sure the binary is in your PATH or use the full path ai
• Verify the binary has execute permissions

Verbose Mode for Debugging

Use the -v flag to see detailed information about what's happening:

ai -v "your command description"

This will show API response times, the generated command, and the raw API response to help diagnose issues.