Bash4LLM⁺

Bash4LLM⁺ is a single-file, self-contained Bash script that wraps Groq's OpenAI-compatible Chat Completions API, making LLM access available directly from any Unix-like terminal. Created by Cristian Evangelisti and released under GPL v3, it is designed to be fully readable and auditable — download it, make it executable, export your API key, and start using it immediately. The project reached v2.0.0 in June 2026 and is actively maintained on GitHub.

What It Is

Bash4LLM⁺ is a CLI tool in the command-line assistant category. Its core job is to let developers, sysadmins, and power users send prompts to LLMs (primarily via Groq, with optional extras for Gemini, Hugging Face, and Mistral) without leaving the shell. Because the entire tool is a single Bash script with no compiled binary, every line of logic is inspectable and modifiable by the user.

Security-First Architecture

The README describes a deliberate threat model targeting single-user environments (PCs, personal servers):

• No use of shared /tmp — temporary files are isolated in a per-run directory with 700 permissions and umask 077
• No eval anywhere in the script; model output is never executed
• Provider files are treated as executable code and must reside in user-owned, secure directories
• TOCTOU risks are documented and mitigated
• Saved output files use 600 permissions
• Advanced provider validation and atomic directory locking (mkdir-based) replace flock on Android/Termux where kernel-level locking is unreliable

Modular Structure and Provider System

The script is organized into named sections — PRECORE_BOOT, PRECORE_RUN, PROVIDER, CORE_SETUP, CORE_PROVIDER — making it straightforward to trace execution flow. The provider system is extensible: the default provider is Groq, but optional extras can add Gemini, Hugging Face, and Mistral support via --install-extras. Model lists are fetched dynamically from the provider API (GET /openai/v1/models) so no models are hardcoded. Model selection follows a clear precedence: CLI flag → per-provider default file → provider auto-selection → whitelist first entry → legacy config.

Key Capabilities

• Streaming and non-streaming output modes
• Interactive REPL chat mode (--chat)
• Session memory via NDJSON history files (--session <id>) with configurable context windows
• Batch processing — one prompt per line from a file
• Template system for reusable prompt structures
• UI State system — atomic JSON files in $BASH4LLM_CONFIG_DIR/ui_state/ expose session metadata, last API result, and provider capabilities for external GUI or Home Assistant integration
• Automatic output saving when response size exceeds a configurable byte threshold
• Dry-run mode for testing without real API calls
• Full diagnostics command for environment validation

Platform Compatibility

Bash4LLM⁺ runs on any Unix-like environment with Bash, coreutils, findutils, util-linux, gawk, curl, and jq in the PATH. Explicitly supported environments include Linux, macOS, WSL, Cygwin, BSD, and Termux on Android. The Termux path receives special handling: the script auto-detects the environment and switches from flock to atomic mkdir-based locking to work around SELinux and kernel limitations common on Android devices.

Update: v2.0.0

The latest release, v2.0.0, was published on June 22, 2026. The repository shows active development with the last push on July 4, 2026. GitHub topics tag the project as supporting groq-api, gemini-api, huggingface-api, and mistral-api, reflecting the multi-provider direction introduced or solidified in this major version. The project previously existed under the name groqshell (still referenced as the GitHub metadata homepage) before being renamed and expanded into Bash4LLM⁺.