# Bash4LLM⁺

> A secure, auditable Bash CLI wrapper for Groq's OpenAI-compatible Chat Completions API, supporting streaming, sessions, multi-provider extras, and Termux/Android environments.

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⁺.

## Features
- Single-file auditable Bash script
- Groq OpenAI-compatible API wrapper
- Dynamic model list via API (no hardcoded models)
- Streaming and non-streaming output
- Interactive REPL chat mode (--chat)
- Session memory with NDJSON history files
- Configurable session context window
- Batch prompt processing from file
- Template system for reusable prompts
- UI State JSON files for GUI/Home Assistant integration
- Automatic output saving with configurable byte threshold
- Dry-run mode
- Multi-provider extras (Gemini, Hugging Face, Mistral)
- No /tmp usage, no eval, restricted permissions
- Atomic directory locking for Termux/Android compatibility
- Full diagnostics command
- Provider validation and whitelist management
- JSON, pretty, text, and raw output modes

## Integrations
Groq API, Gemini API, Hugging Face API, Mistral API, Home Assistant, curl, jq

## Platforms
MACOS, LINUX, ANDROID, API, CLI

## Pricing
Open Source

## Version
v2.0.0

## Links
- Website: https://github.com/kamaludu/bash4llm
- Documentation: https://github.com/kamaludu/bash4llm
- Repository: https://github.com/kamaludu/bash4llm
- EveryDev.ai: https://www.everydev.ai/tools/bash4llm