bash4llm

Bash-first CLI wrapper for OpenAI-compatible LLM APIs

TLDR

Send a prompt to the default Groq provider

$ bash4llm "[prompt]"

Run a prompt from a file

$ bash4llm -f [prompt.txt]

Use a specific model for one request

$ bash4llm -m [llama-3.3-70b-versatile] "[prompt]"

Start interactive chat mode

$ bash4llm --chat

Refresh the model list from the provider API

$ bash4llm --refresh-models

Enable contextual memory across turns in a named session

$ bash4llm --session [chat1] "[prompt]"

bash4llm (Bash4LLM⁺) is a single self-contained Bash script that wraps OpenAI-compatible chat completion APIs, with Groq as the default provider. It is designed to be readable, auditable, and portable across Linux, macOS, WSL, Cygwin, Termux, and BSD systems.The script fetches model lists dynamically from the provider API rather than hardcoding them, supports streaming and non-streaming responses, and can pipe input from files or standard input. Optional extras add more providers such as Gemini, Hugging Face, and Mistral. Session support stores turn history in NDJSON files when --session is used, giving short-term contextual memory without keeping state by default.Security is a core design goal: the script avoids eval, never executes model output, does not use shared /tmp directories, and isolates temporary files with restrictive permissions. Provider modules are treated as trusted code and should live in directories owned by the user.

PARAMETERS

-f file

Read prompt text from file.

-m, --model model

Use model for this run only.

--provider name

Select an installed provider (for example groq or gemini).

--system text

Set the system prompt.

--temperature, --ture n

Set sampling temperature between 0.0 and 2.0.

--max n

Limit maximum output tokens.

--session id

Enable session memory for contextual follow-up prompts.

--session-window [n]

Limit how many prior session turns are included (default 10).

--stream, --no-stream

Enable or disable streaming output.

--chat

Start an interactive REPL chat session.

--dry-run

Validate configuration without calling the API.

--json, --pretty, --text, --raw

Control response output format.

--save, --nosave, --out path, --threshold bytes

Control automatic saving of long responses.

--refresh-models, --list-models, --list-providers

Manage and inspect provider model lists.

--set-default model

Persist the default model for the active provider.

--install-extras [dir]

Install optional provider packs, templates, and tools.

--show-config, --diagnostics

Print active configuration or run system checks.

-h, --help

Show help.

--version

Print version and exit.

CONFIGURATION

$BASH4LLM_CONFIG_DIR/config

Local settings such as model, temperature, max tokens, output format, and save threshold.

$BASH4LLM_CONFIG_DIR/model.$PROVIDER

Persistent default model for a provider.

$BASH4LLM_CONFIG_DIR/ui_state/

Atomic JSON metadata for external tools and optional GUI integrations.

$BASH4LLM_HISTORY_DIR/sessions/<id>.ndjson

Session conversation history when --session is enabled.

GROQ_API_KEY

API key for the default Groq provider.

BASH4LLM_TMPDIR

Private temporary directory used instead of system /tmp.

Model selection precedence is: -m/--model, then model.$PROVIDER, then provider auto-selection, then the first whitelisted model, then the legacy global config file.

EXIT CODES

Success.

Missing API key.

Invalid or non-whitelisted model.

Network or curl failure.

No prompt provided.

Filesystem or temporary-file error.

Provider HTTP or API error.

CAVEATS

Requires bash, curl, jq, gawk, and common coreutils on PATH. Contextual memory exists only when --session is supplied on every related call. Provider extras are executable shell code and must be kept in trusted directories. On Termux, file locking falls back to atomic directory locks because flock is often unreliable.

RESOURCES

Source code