Show HN: Bash4LLM+ – A lightweight, dependency-free Bash wrapper for LLM APIs

A developer released Bash4LLM⁺, a lightweight, dependency-free Bash wrapper for LLM APIs that provides a secure, Bash-first CLI for OpenAI-compatible Chat Completions via Groq, with modular architecture, streaming, and dynamic model lists. The tool is designed for Unix-like environments and emphasizes auditability and safety by avoiding /tmp and eval.

Bash4LLM⁺ 🇮🇹 🇬🇧 /kamaludu/bash4llm/blob/main/README-en.md Bash4LLM⁺ — wrapper CLI sicuro, Bash‑first e completamente auditabile per l’API Chat Completions compatibile OpenAI di Groq ed estendibile ad altri provider . Bash4LLM⁺ è un singolo script Bash, auto‑contenuto, leggibile e verificabile. Scaricalo, rendilo eseguibile, esporta la tua API key e inizia subito a usarlo. Compatibile con ambienti Unix‑like: Linux, macOS, WSL, Cygwin, Termux Android , BSD. - Lista modelli dinamica tramite GET https://api.groq.com/openai/v1/models → nessun modello hardcoded. - Sicurezza by design → nessun uso di /tmp , nessun eval , permessi restrittivi, validazione provider avanzata. - Struttura modulare a sezioni → PRECORE BOOT, PRECORE RUN, PROVIDER, CORE SETUP, CORE PROVIDER. - Sistema di Stato UI ui state → il CORE espone costantemente metadati in formato JSON atomico per l'integrazione con GUI o strumenti esterni es. Home Assistant . - Streaming e non‑streaming → output in tempo reale o completo a fine risposta. - Salvataggio automatico → per output lunghi oltre una soglia configurabile. - Gestione modelli avanzata → refresh, lista, default persistente, whitelist dinamica, auto‑selezione. - Extras opzionali → provider aggiuntivi come Gemini, Hugging Face, Mistral , template, documentazione, strumenti di sicurezza. - Pronto per Termux / Android → rileva automaticamente l'ambiente Termux bypassando flock spesso instabile o limitato a livello kernel/SELinux su Android e devia trasparentemente la gestione della concorrenza sul robusto meccanismo di directory lock mkdir atomico . Bash4LLM⁺ è progettato per ambienti single‑user PC/laptop, server personali . - I provider sono codice eseguito nella tua shell: devono risiedere in directory sicure di tua proprietà. - Variabili come BASH4LLM EXTRAS DIR e BASH4LLM TMPDIR sono considerate configurazione fidata. - Lo script non esegue mai l’output del modello. - I rischi TOCTOU e i limiti del parsing JSON/SSE sono mitigati e documentati. Dettagli completi in SECURITY . Bash4LLM⁺ richiede che i seguenti pacchetti o equivalenti siano disponibili nel PATH: bash - coreutils - findutils - util-linux - gawk - curl - jq Tip ⏩ FAST FORWARD Installazione Rapida Esegui questi comandi nel tuo terminale per avviare subito Bash4LLM⁺ : 1. Clona il repository solo l'ultimo commit per massima velocità git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm 2. Crea una cartella di lavoro ed estrai l'eseguibile mkdir -p bash4llm cp repo-bash4llm/bin/bash4llm bash4llm/ chmod +x bash4llm/bash4llm 3. Entra nella cartella e aggiorna i modelli cd bash4llm ./bash4llm --refresh-models Lo script ti chiederà l'inserimento della tua chiave API per il provider di default Groq : Enter API key for provider groq env GROQ API KEY : Inserisci la tua API key, poi esportala per non doverla più inserire durante la sessione: export GROQ API KEY="gsk xxxxxxxxxxxxxxxxx" Consigliato: installa gli Extras opzionali : 4. Installazione degli Extras ./bash4llm --install-extras ../repo-bash4llm/extras/ Usa Bash4llm ⚡ Istruzioni dettagliate in: INSTALL /kamaludu/bash4llm/blob/main/INSTALL.md In breve: chmod +x bash4llm export GROQ API KEY="gsk xxxxxxxxxxxxxxxxx" ./bash4llm --help Extras opzionali: ./bash4llm --install-extras Con opzioni: --source <dir --force --dry-run - installazione selettiva: ./bash4llm --install-extras provider1 templateA Prompt diretto: ./bash4llm "scrivi una breve poesia in italiano" Prompt multilinea: ./bash4llm <<'EOF' scrivi una breve poesia in italiano EOF Input da file: ./bash4llm -f prompt.txt Pipe: echo "spiegami la relatività" | ./bash4llm Modello specifico: ./bash4llm -m llama-3.3-70b-versatile "scrivi un saggio breve" Dry run: ./bash4llm --dry-run "ciao" Provider esterno se installato : ./bash4llm --provider gemini "traduci questo" | Flag | Argomento | Effetto | |---|---|---| --refresh-models , --refresh-model | no | Aggiorna la lista modelli richiede API key . | --list-models | no | Stampa lista modelli formato interattivo . | --list-models-raw | no | Stampa lista modelli in formato raw una riga per modello . | --list-providers | no | Stampa lista provider. | --list-providers-raw | no | Stampa provider in formato raw. | --set-default <model | sì | Imposta modello di default persistente per il provider attivo. | -m <model , --model <model | sì | Imposta modello per questa esecuzione. | --provider <name | sì | Imposta provider da CLI. | --provider | no | Se senza argomento → apre selezione interattiva. | | Flag | Argomento | Effetto | |---|---|---| -f <file | sì | Aggiunge file a FILE INPUTS . | --json-input <json | sì | Imposta input JSON formato OpenAI-like . | --template <name | sì | Applica template da BASH4LLM TEMPLATES DIR . | --batch <file | sì | Esegue richieste batch una riga = un prompt . | | Flag | Argomento | Effetto | |---|---|---| --session <id | sì | Abilita sessione con ID specifico. | --session-window n | opzionale | Imposta finestra sessione default 10 se non fornito . | --init-session | si | Inizializza in sicurezza una sessione vuota creando i file NDJSON e i metadati e la registra nell'indice globale delle sessioni, senza effettuare chiamate API. Richiede l'uso congiunto di --session <id . | | Flag | Argomento | Effetto | |---|---|---| --system <text | sì | Imposta system prompt. | --ture <n | sì | Imposta parametro temperatura da 0.0 a 2.0, alias canonico . | --temperature <n | sì | Alias di --ture . | --max <n | sì | Imposta max token. | | Flag | Argomento | Effetto | |---|---|---| --save | no | Forza salvataggio output. | --nosave | no | Disabilita salvataggio. | --out <path | sì | Percorso file/directory output. | --threshold <n | sì | Soglia dimensione in byte per salvataggio automatico default: 1000 . | --json | no | Output JSON raw integro. | --pretty | no | Output JSON formattato. | --text | no | Output testuale standard estratto comportamento predefinito . | --raw | no | Output testuale grezzo escludendo separazioni finali. | | Flag | Argomento | Effetto | |---|---|---| --dry-run | no | Nessuna chiamata API reale comportamento simulato . | --quiet | no | Riduce l'output non necessario e sopprime i titoli su TTY. | --stream | no | Streaming asincrono attivo. | --no-stream | no | Disattiva streaming asincrono. | --chat | no | Modalità chat interattiva REPL. | --bootstrap-only | no | Esegue solo validazione percorsi/lock e termina. | | Flag | Argomento | Effetto | |---|---|---| --show-config | no | Mostra configurazione completa attiva. | --diagnostics | no | Esegue diagnostica completa del sistema. | --version | no | Stampa versione dello script e termina. | -h , --help | no | Mostra help interattivo formattato da file. | | Flag | Argomento | Effetto | |---|---|---| --install-extras | opzionale | Installa extras; può accettare directory sorgente. | --install-extras=<dir | sì | Installa extras da directory sorgente specifica. | | Flag | Effetto | |---|---| -- | Termina parsing opzioni. | - | Opzione sconosciuta → errore. | | Argomento posizionale → aggiunto a ARGS . | - $BASH4LLM CONFIG DIR/config → parametri locali MODEL, TURE, MAX TOKENS, FORMAT, THRESHOLD - $BASH4LLM CONFIG DIR/model.$PROVIDER → modello predefinito per provider - $MODELS FILE → whitelist modelli aggiornata da --refresh-models -m/--model model.$PROVIDER - auto‑selezione provider auto select model <provider - prima voce della whitelist models.txt - configurazione globale legacy config MODEL=... - Nessun uso di /tmp a livello di sistema operativo condiviso. - File temporanei isolati in directory $RUN TMPDIR con permessi 700 umask 077 . - File salvati con permessi 600 . - Con --out Bash4LLM⁺ crea la directory se possibile. Bash4LLM⁺ espone metadati operativi destinati a GUI/strumenti esterni tramite file JSON atomici in: $BASH4LLM CONFIG DIR/ui state Contiene: sessions/<id .json → stato sessione active, msg count, last ts sessions/index.json → elenco sessioni last api.json → ultimo risultato API http status, req id, edgecase detected, ecc. last history.json → ultimo salvataggio history provider capabilities.json → capacità provider attivo streaming, refresh models La GUI extra opzionale legge solo questi file per i placeholder CGI. Bash4LLM⁺ non mantiene memoria da solo . La memoria esiste solo se attivi una sessione tramite --session . Ogni sessione crea un file NDJSON persistente: $BASH4LLM HISTORY DIR/sessions/<session id .ndjson E Bash4LLM⁺ mantiene i metadati della sessione in: $BASH4LLM CONFIG DIR/ui state/sessions/<session id .json Questi metadati sono la fonte canonica per GUI/strumenti esterni. ./bash4llm --session chat1 "Ciao" ./bash4llm --session chat1 "Riassumi ciò che ho detto" ./bash4llm --session chat1 --session-window 10 "continua" Per avere memoria contestuale devi sempre includere --session <id . - Nessun eval . - Nessuna esecuzione dell’output del modello. - Provider = codice: mantieni extras/providers sicuro. - Variabili d’ambiente = configurazione fidata. - TOCTOU mitigato. | Codice | Variabile | Significato | |---|---|---| 0 | - | Successo | 10 | BASH4LLM ERR NO API KEY | API key mancante | 11 | BASH4LLM ERR BAD MODEL | Modello non valido o non in whitelist | 12 | BASH4LLM ERR CURL FAILED | Errore rete/curl | 14 | BASH4LLM ERR NO PROMPT | Nessun prompt fornito | 15 | BASH4LLM ERR TMP | Errore generico filesystem / temporanei | 16 | BASH4LLM ERR API | Errore HTTP/API del fornitore | | Variabile | Necessaria | Descrizione | |---|---|---| GROQ API KEY | sì per chiamate API | API key provider Groq. | BASH4LLM CONFIG DIR | consigliata | Directory configurazione. | BASH4LLM MODELS DIR | consigliata | Directory modelli. | BASH4LLM TMPDIR | sì | Directory temporanea. | BASH4LLM HISTORY DIR | consigliata | Directory sessioni e cronologia. | MODEL | no | Modello attivo. | PROVIDER | no | Provider attivo. | ALLOWED MODELS | no | Whitelist modelli ammessi. | Bash4LLM⁺ è distribuito sotto licenza GPL v3. Vedi LICENSE . Autore: Cristian Evangelisti Email: opensource@cevangel.anonaddy.me Repository: https://github.com/kamaludu/bash4llm https://github.com/kamaludu/bash4llm