AI Shell

Converts plain English descriptions into executable shell commands by streaming OpenAI API responses and parsing structured command output. The system accepts natural language prompts, formats them with system context about the user's shell environment, sends them to OpenAI's language models via streaming API, and extracts the generated command from the response stream. This eliminates the need for users to recall complex command syntax or flags.

Provides a user-facing workflow where generated commands are displayed with explanations before execution, allowing users to review, edit, or reject commands via interactive prompts. The CLI uses cleye library for command routing and presents generated commands with a confirmation step, enabling users to modify commands in-place or request regeneration before they execute in the actual shell.

Uses the cleye library to parse command-line arguments and route user input to appropriate command handlers (ai, ai chat, ai config, ai update). The cleye library provides a declarative command structure that maps CLI arguments to handler functions, managing flag parsing, help text generation, and command routing. This enables the tool to support multiple commands and subcommands with consistent argument handling.

Provides an ai update command that checks for newer versions of AI Shell and upgrades the tool to the latest version from npm. The update mechanism uses npm's package management system to detect and install newer versions, allowing users to keep the tool current without manual reinstallation. This is implemented as a dedicated command handler that invokes npm update or equivalent.

Processes OpenAI API streaming responses in real-time using a stream-to-string helper utility that accumulates chunks and displays them incrementally to the terminal. The implementation reads from the streaming response body, buffers chunks, and outputs them as they arrive, providing immediate visual feedback rather than waiting for the complete API response. This is handled through Node.js stream APIs and custom buffering logic.

Provides user interface text in 14+ languages (English, Chinese, Spanish, Japanese, Korean, French, German, Russian, Ukrainian, Vietnamese, Arabic, Portuguese, Turkish, Indonesian) through a configuration-driven internationalization system. The system maps language codes to localized strings for prompts, explanations, and error messages, allowing users to configure their preferred language via the config command and have all CLI output rendered in that language.

Manages user preferences (API key, language, model selection, custom settings) through a persistent configuration file system using the config command. Configuration is stored in a user-accessible location (typically ~/.ai-shell/config.json) and loaded on each invocation, allowing users to set preferences once and have them apply across all future commands without re-entering them.

Provides a --silent or -s flag that skips explanation generation and user confirmation, outputting only the generated shell command directly to stdout. This mode bypasses the interactive workflow entirely, making the tool suitable for scripting and automation scenarios where the command output can be piped directly to a shell or captured for further processing.

Provides an interactive chat mode (ai chat command) that maintains conversation context across multiple turns, allowing users to refine command generation through back-and-forth dialogue. The chat mode uses the same OpenAI API integration but maintains conversation history, allowing users to ask follow-up questions, request modifications, or explore alternative commands without restarting the conversation.

Generates human-readable explanations of what generated shell commands do by making a separate OpenAI API call that breaks down command components, flags, and their effects. The explanation is displayed alongside the command before execution, helping users understand the command's behavior and verify it matches their intent. Explanations are generated using the same OpenAI API but with a different prompt focused on clarity rather than command generation.

Integrates with OpenAI's API using the official Node.js SDK, supporting configurable model selection (GPT-4, GPT-3.5-turbo, etc.) and streaming responses. The integration handles API authentication via OPENAI_API_KEY environment variable or configuration file, manages request formatting with system prompts that provide shell context, and processes streaming responses in real-time. Users can configure which OpenAI model to use via the config command.

Injects information about the user's shell environment (shell type, OS, current directory context) into the system prompt sent to OpenAI, enabling the model to generate OS-specific and shell-specific commands. The system detects the user's shell (bash, zsh, fish, etc.) and operating system, then includes this context in the prompt so generated commands are appropriate for the user's actual environment rather than generic.