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
tramiteGET https://api.groq.com/openai/v1/models
→ nessun modello hardcoded. - Sicurezza by design
→ nessun uso di/tmp
, nessuneval
, 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 bypassandoflock
(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
eBASH4LLM_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⁺:
git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm
mkdir -p bash4llm
cp repo-bash4llm/bin/bash4llm bash4llm/
chmod +x bash4llm/bash4llm
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*:
./bash4llm --install-extras ../repo-bash4llm/extras/
Usa Bash4llm ⚡
Istruzioni dettagliate in: INSTALL
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 permessi700
(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 sessionilast_api.json
→ ultimo risultato API (http_status, req_id, edgecase_detected, ecc.)last_history.json
→ ultimo salvataggio historyprovider_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