GroqBash CLI License: GPLv3 ShellCheck Smoke Tests

GroqBash English

GroqBash — wrapper CLI sicuro, Bash‐first e completamente auditabile per l’API Chat Completions compatibile OpenAI di Groq.

GroqBash è 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, Termux.

Caratteristiche principali

• Lista modelli dinamica
  tramite GET https://api.groq.com/openai/v1/models
  → nessun modello hardcoded, nessun fallback nascosto.

• Sicurezza by design
  → nessun uso di /tmp, nessun eval, permessi restrittivi, controlli provider robusti.

• Bash‐first
  → logica chiara, nessuna dipendenza non necessaria.

• 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, auto‐selezione basata su policy.

• Extras opzionali
  → provider, documentazione estesa, strumenti di sicurezza, test.

Modello di minaccia (versione breve)

GroqBash è progettato per ambienti single‐user (laptop, Termux, shell personale).

• I provider sono codice eseguito nella tua shell: devono risiedere in directory sicure e non scrivibili da altri.
• Variabili come GROQBASHEXTRASDIR e GROQBASHTMPDIR 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.

Per dettagli completi: SECURITY .

Requisiti

Minimi

• bash
• curl
• coreutils (mktemp, chmod, mv, mkdir, head, sed, awk, grep)

Consigliati

• jq (parsing JSON)
• python3 (fsync opzionale)
• sha256sum o shasum (per extras di sicurezza)

Installazione

Istruzioni dettagliate in INSTALL .

In breve:

chmod +x groqbash
export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxx"
./groqbash --help

Extras opzionali (docs, provider, sicurezza, test):

./groqbash --install-extras

Uso rapido

Prompt diretto:

./groqbash "scrivi una breve poesia in italiano"

Input da file:

./groqbash -f prompt.txt

Pipe:

echo "spiegami la relatività" | ./groqbash

Modello specifico:

./groqbash -m llama-3.3-70b-versatile "scrivi un saggio breve"

Dry run (mostra il payload JSON):

./groqbash --dry-run "ciao"

Provider (se extras installati):

./groqbash --provider gemini "traduci questo"

Opzioni principali

Configurazione e comportamento modelli

File di configurazione

• ~/.config/groq/models.txt
  → lista modelli dinamica (ricreata a ogni refresh).
• ~/.config/groq/default_model
  → modello predefinito persistente.

Precedenza selezione modello

1. -m/--model
2. default_model
3. GROQ_MODEL
4. Auto‐selezione basata su policy

Se la lista modelli è vuota: errore → richiede --refresh-models.

Refresh modelli

./groqbash --refresh-models

Scarica la lista ufficiale, ricostruisce models.txt, mostra diagnostica (più dettagli con --debug).

File temporanei e percorsi output

• GroqBash non usa mai /tmp.
• I temporanei runtime sono creati con mktemp -d e permessi 700.
• I file salvati hanno permessi restrittivi (600).
• Con --out, GroqBash crea la directory se possibile; altrimenti stampa su terminale.

Extras avanzati (opzionali)

Gli extras non modificano il comportamento del core.

Sicurezza

• extras/security/verify.sh
  → verifica provider, permessi, symlink, owner, checksum.
• extras/security/validate-env.sh
  → controlla GROQBASHEXTRASDIR, GROQBASHTMPDIR, strumenti richiesti.

Esecuzione:

extras/security/verify.sh
extras/security/validate-env.sh

Test

• extras/test/json-sse-suite.sh
  → test per escaping JSON e parsing SSE (senza chiamate API reali).

Note di sicurezza e limitazioni

• Nessun eval.
• Nessuna esecuzione dell’output del modello.
• Provider = codice: mantieni extras/providers sicuro.
• Variabili d’ambiente = configurazione fidata.
• Parsing JSON/SSE: robusto ma non un parser completo.
• TOCTOU: mitigato ma non eliminabile in Bash.

Per dettagli completi: SECURITY.md.

Codici di uscita

Licenza

GroqBash è distribuito sotto licenza GNU GPL v3.
Vedi LICENSE per il testo completo.

Note

Parte del codice e della documentazione è stata redatta con l’assistenza di strumenti di IA.
L’architettura e le decisioni tecniche restano curate manualmente.

Contatti

• Autore: Cristian Evangelisti
• Email: opensource​@​cevangel.​anonaddy.​me
• Repository: https://github.com/kamaludu/groqbash