{"slug": "show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis", "title": "Show HN: Bash4LLM+ – A lightweight, dependency-free Bash wrapper for LLM APIs", "summary": "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.", "body_md": "# Bash4LLM⁺ 🇮🇹 [🇬🇧](/kamaludu/bash4llm/blob/main/README-en.md)\n\n**Bash4LLM⁺** — wrapper CLI sicuro, Bash‑first e completamente auditabile per l’API Chat Completions compatibile OpenAI di Groq (ed estendibile ad altri provider).\n\nBash4LLM⁺ è un singolo script Bash, auto‑contenuto, leggibile e verificabile.\n\nScaricalo, rendilo eseguibile, esporta la tua API key e inizia subito a usarlo.\n\nCompatibile con ambienti Unix‑like: Linux, macOS, WSL, Cygwin, Termux (Android), BSD.\n\n-\n**Lista modelli dinamica**\n\ntramite`GET https://api.groq.com/openai/v1/models`\n\n→ nessun modello hardcoded. -\n**Sicurezza by design**\n\n→ nessun uso di`/tmp`\n\n, nessun`eval`\n\n, permessi restrittivi, validazione provider avanzata. -\n**Struttura modulare a sezioni**\n\n→ PRECORE_BOOT, PRECORE_RUN, PROVIDER, CORE_SETUP, CORE_PROVIDER. -\n**Sistema di Stato UI (ui_state)**\n\n→ il CORE espone costantemente metadati in formato JSON atomico per l'integrazione con GUI o strumenti esterni (es. Home Assistant). -\n**Streaming e non‑streaming**\n\n→ output in tempo reale o completo a fine risposta. -\n**Salvataggio automatico**\n\n→ per output lunghi oltre una soglia configurabile. -\n**Gestione modelli avanzata**\n\n→ refresh, lista, default persistente, whitelist dinamica, auto‑selezione. -\n**Extras opzionali**\n\n→ provider aggiuntivi (come Gemini, Hugging Face, Mistral), template, documentazione, strumenti di sicurezza. -\n**Pronto per Termux / Android**\n\n→ rileva automaticamente l'ambiente Termux bypassando`flock`\n\n(spesso instabile o limitato a livello kernel/SELinux su Android) e devia trasparentemente la gestione della concorrenza sul robusto meccanismo di directory lock (`mkdir`\n\natomico).\n\nBash4LLM⁺ è progettato per ambienti single‑user (PC/laptop, server personali).\n\n- I provider sono codice eseguito nella tua shell: devono risiedere in directory sicure di tua proprietà.\n- Variabili come\n`BASH4LLM_EXTRAS_DIR`\n\ne`BASH4LLM_TMPDIR`\n\nsono considerate configurazione fidata. - Lo script non esegue mai l’output del modello.\n- I rischi TOCTOU e i limiti del parsing JSON/SSE sono mitigati e documentati.\n\nDettagli completi in ** SECURITY**.\n\nBash4LLM⁺ richiede che i seguenti pacchetti (o equivalenti) siano disponibili nel PATH:\n\n**bash**- coreutils\n- findutils\n- util-linux\n- gawk\n- curl\n- jq\n\nTip\n\n**⏩ FAST FORWARD (Installazione Rapida)**\n\nEsegui questi comandi nel tuo terminale per avviare subito **Bash4LLM⁺**:\n\n```\n# 1. Clona il repository (solo l'ultimo commit per massima velocità)\ngit clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm  \n\n# 2. Crea una cartella di lavoro ed estrai l'eseguibile\nmkdir -p bash4llm\ncp repo-bash4llm/bin/bash4llm bash4llm/\nchmod +x bash4llm/bash4llm\n\n# 3. Entra nella cartella e aggiorna i modelli \ncd bash4llm \n./bash4llm --refresh-models\n```\n\nLo script ti chiederà l'inserimento della tua chiave API per il provider di default (Groq):\n`Enter API key for provider groq (env GROQ_API_KEY):`\n\nInserisci la tua API key, poi esportala per non doverla più inserire durante la sessione:\n\n`export GROQ_API_KEY=\"gsk_xxxxxxxxxxxxxxxxx\"`\n\nConsigliato: * installa gli Extras opzionali*:\n\n```\n# 4. Installazione degli Extras\n./bash4llm --install-extras ../repo-bash4llm/extras/\n```\n\nUsa Bash4llm ⚡\n\nIstruzioni dettagliate in: [INSTALL](/kamaludu/bash4llm/blob/main/INSTALL.md)\n\nIn breve:\n\n```\nchmod +x bash4llm\nexport GROQ_API_KEY=\"gsk_xxxxxxxxxxxxxxxxx\"\n./bash4llm --help\n```\n\nExtras opzionali:\n\n```\n./bash4llm --install-extras\n```\n\nCon opzioni:\n\n`--source <dir>`\n\n`--force`\n\n`--dry-run`\n\n- installazione selettiva:\n\n`./bash4llm --install-extras provider1 templateA`\n\nPrompt diretto:\n\n```\n./bash4llm \"scrivi una breve poesia in italiano\"\n```\n\nPrompt multilinea:\n\n```\n./bash4llm <<'EOF'\nscrivi una breve poesia\nin italiano\nEOF\n```\n\nInput da file:\n\n```\n./bash4llm -f prompt.txt\n```\n\nPipe:\n\n```\necho \"spiegami la relatività\" | ./bash4llm\n```\n\nModello specifico:\n\n```\n./bash4llm -m llama-3.3-70b-versatile \"scrivi un saggio breve\"\n```\n\nDry run:\n\n```\n./bash4llm --dry-run \"ciao\"\n```\n\nProvider esterno (se installato):\n\n```\n./bash4llm --provider gemini \"traduci questo\"\n```\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--refresh-models` , `--refresh-model` |\nno | Aggiorna la lista modelli (richiede API key). |\n`--list-models` |\nno | Stampa lista modelli (formato interattivo). |\n`--list-models-raw` |\nno | Stampa lista modelli in formato raw (una riga per modello). |\n`--list-providers` |\nno | Stampa lista provider. |\n`--list-providers-raw` |\nno | Stampa provider in formato raw. |\n`--set-default <model>` |\nsì | Imposta modello di default persistente per il provider attivo. |\n`-m <model>` , `--model <model>` |\nsì | Imposta modello per questa esecuzione. |\n`--provider <name>` |\nsì | Imposta provider da CLI. |\n`--provider` |\nno | Se senza argomento → apre selezione interattiva. |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`-f <file>` |\nsì | Aggiunge file a `FILE_INPUTS` . |\n`--json-input <json>` |\nsì | Imposta input JSON (formato OpenAI-like). |\n`--template <name>` |\nsì | Applica template da `BASH4LLM_TEMPLATES_DIR` . |\n`--batch <file>` |\nsì | Esegue richieste batch (una riga = un prompt). |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--session <id>` |\nsì | Abilita sessione con ID specifico. |\n`--session-window [n]` |\nopzionale | Imposta finestra sessione (default 10 se non fornito). |\n`--init-session` |\nsi | 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>` . |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--system <text>` |\nsì | Imposta system prompt. |\n`--ture <n>` |\nsì | Imposta parametro temperatura (da 0.0 a 2.0, alias canonico). |\n`--temperature <n>` |\nsì | Alias di `--ture` . |\n`--max <n>` |\nsì | Imposta max token. |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--save` |\nno | Forza salvataggio output. |\n`--nosave` |\nno | Disabilita salvataggio. |\n`--out <path>` |\nsì | Percorso file/directory output. |\n`--threshold <n>` |\nsì | Soglia dimensione in byte per salvataggio automatico (default: 1000). |\n`--json` |\nno | Output JSON raw integro. |\n`--pretty` |\nno | Output JSON formattato. |\n`--text` |\nno | Output testuale standard estratto (comportamento predefinito). |\n`--raw` |\nno | Output testuale grezzo escludendo separazioni finali. |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--dry-run` |\nno | Nessuna chiamata API reale (comportamento simulato). |\n`--quiet` |\nno | Riduce l'output non necessario e sopprime i titoli su TTY. |\n`--stream` |\nno | Streaming asincrono attivo. |\n`--no-stream` |\nno | Disattiva streaming asincrono. |\n`--chat` |\nno | Modalità chat interattiva REPL. |\n`--bootstrap-only` |\nno | Esegue solo validazione percorsi/lock e termina. |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--show-config` |\nno | Mostra configurazione completa attiva. |\n`--diagnostics` |\nno | Esegue diagnostica completa del sistema. |\n`--version` |\nno | Stampa versione dello script e termina. |\n`-h` , `--help` |\nno | Mostra help interattivo formattato da file. |\n\n| Flag | Argomento | Effetto |\n|---|---|---|\n`--install-extras` |\nopzionale | Installa extras; può accettare directory sorgente. |\n`--install-extras=<dir>` |\nsì | Installa extras da directory sorgente specifica. |\n\n| Flag | Effetto |\n|---|---|\n`--` |\nTermina parsing opzioni. |\n`-*` |\nOpzione sconosciuta → errore. |\n`*` |\nArgomento posizionale → aggiunto a `ARGS` . |\n\n-\n`$BASH4LLM_CONFIG_DIR/config`\n\n→ parametri locali (MODEL, TURE, MAX_TOKENS, FORMAT, THRESHOLD) -\n`$BASH4LLM_CONFIG_DIR/model.$PROVIDER`\n\n→ modello predefinito per provider -\n`$MODELS_FILE`\n\n→ whitelist modelli aggiornata da`--refresh-models`\n\n`-m/--model`\n\n`model.$PROVIDER`\n\n- auto‑selezione provider (\n`auto_select_model_<provider>`\n\n) - prima voce della whitelist (\n`models.txt`\n\n) - configurazione globale legacy\n`config`\n\n(`MODEL=...`\n\n)\n\n- Nessun uso di\n`/tmp`\n\na livello di sistema operativo condiviso. - File temporanei isolati in directory\n`$RUN_TMPDIR`\n\ncon permessi`700`\n\n(`umask 077`\n\n). - File salvati con permessi\n`600`\n\n. - Con\n`--out`\n\nBash4LLM⁺ crea la directory se possibile.\n\nBash4LLM⁺ espone metadati operativi destinati a GUI/strumenti esterni tramite file JSON atomici in:\n\n```\n$BASH4LLM_CONFIG_DIR/ui_state\n```\n\nContiene:\n\n`sessions/<id>.json`\n\n→ stato sessione (active, msg_count, last_ts)`sessions/index.json`\n\n→ elenco sessioni`last_api.json`\n\n→ ultimo risultato API (http_status, req_id, edgecase_detected, ecc.)`last_history.json`\n\n→ ultimo salvataggio history`provider_capabilities.json`\n\n→ capacità provider attivo (streaming, refresh_models)\n\nLa GUI (extra opzionale) legge **solo** questi file per i placeholder CGI.\n\nBash4LLM⁺ **non mantiene memoria da solo**.\n\nLa memoria esiste **solo se attivi una sessione** tramite `--session`\n\n.\n\nOgni sessione crea un file NDJSON persistente:\n\n```\n$BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson\n```\n\nE Bash4LLM⁺ mantiene i metadati della sessione in:\n\n```\n$BASH4LLM_CONFIG_DIR/ui_state/sessions/<session_id>.json\n```\n\nQuesti metadati sono la fonte canonica per GUI/strumenti esterni.\n\n```\n./bash4llm --session chat1 \"Ciao\"\n./bash4llm --session chat1 \"Riassumi ciò che ho detto\"\n./bash4llm --session chat1 --session-window 10 \"continua\"\n```\n\nPer avere memoria contestuale **devi sempre** includere `--session <id>`\n\n.\n\n- Nessun\n`eval`\n\n. - Nessuna esecuzione dell’output del modello.\n- Provider = codice: mantieni\n`extras/providers`\n\nsicuro. - Variabili d’ambiente = configurazione fidata.\n- TOCTOU mitigato.\n\n| Codice | Variabile | Significato |\n|---|---|---|\n0 |\n- | Successo |\n10 |\n`BASH4LLM_ERR_NO_API_KEY` |\nAPI key mancante |\n11 |\n`BASH4LLM_ERR_BAD_MODEL` |\nModello non valido o non in whitelist |\n12 |\n`BASH4LLM_ERR_CURL_FAILED` |\nErrore rete/curl |\n14 |\n`BASH4LLM_ERR_NO_PROMPT` |\nNessun prompt fornito |\n15 |\n`BASH4LLM_ERR_TMP` |\nErrore generico filesystem / temporanei |\n16 |\n`BASH4LLM_ERR_API` |\nErrore HTTP/API del fornitore |\n\n| Variabile | Necessaria | Descrizione |\n|---|---|---|\n`GROQ_API_KEY` |\nsì per chiamate API | API key provider Groq. |\n`BASH4LLM_CONFIG_DIR` |\nconsigliata | Directory configurazione. |\n`BASH4LLM_MODELS_DIR` |\nconsigliata | Directory modelli. |\n`BASH4LLM_TMPDIR` |\nsì | Directory temporanea. |\n`BASH4LLM_HISTORY_DIR` |\nconsigliata | Directory sessioni e cronologia. |\n`MODEL` |\nno | Modello attivo. |\n`PROVIDER` |\nno | Provider attivo. |\n`ALLOWED_MODELS` |\nno | Whitelist modelli ammessi. |\n\nBash4LLM⁺ è distribuito sotto licenza GPL v3.\n\nVedi ** LICENSE**.\n\nAutore: Cristian Evangelisti\n\nEmail: opensource@cevangel.anonaddy.me\n\nRepository: [https://github.com/kamaludu/bash4llm](https://github.com/kamaludu/bash4llm)", "url": "https://wpnews.pro/news/show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis", "canonical_source": "https://github.com/kamaludu/bash4llm/", "published_at": "2026-06-28 19:43:10+00:00", "updated_at": "2026-06-28 22:58:10.726935+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-tools"], "entities": ["Groq", "OpenAI", "Bash4LLM⁺", "Termux", "Home Assistant", "Gemini", "Hugging Face", "Mistral"], "alternates": {"html": "https://wpnews.pro/news/show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis", "markdown": "https://wpnews.pro/news/show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis.md", "text": "https://wpnews.pro/news/show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis.txt", "jsonld": "https://wpnews.pro/news/show-hn-bash4llm-a-lightweight-dependency-free-bash-wrapper-for-llm-apis.jsonld"}}