Skip to content

Commit 46edfd9

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent c2fb2a5 commit 46edfd9

2 files changed

Lines changed: 160 additions & 0 deletions

File tree

‎assets/commands/bash4llm.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# TAGLINE
2+
3+
Bash-first CLI wrapper for OpenAI-compatible LLM APIs
4+
5+
# TLDR
6+
7+
**Send a prompt** to the default Groq provider
8+
9+
```bash4llm "[prompt]"```
10+
11+
**Run a prompt from a file**
12+
13+
```bash4llm -f [prompt.txt]```
14+
15+
**Use a specific model** for one request
16+
17+
```bash4llm -m [llama-3.3-70b-versatile] "[prompt]"```
18+
19+
**Start interactive chat** mode
20+
21+
```bash4llm --chat```
22+
23+
**Refresh the model list** from the provider API
24+
25+
```bash4llm --refresh-models```
26+
27+
**Enable contextual memory** across turns in a named session
28+
29+
```bash4llm --session [chat1] "[prompt]"```
30+
31+
# SYNOPSIS
32+
33+
**bash4llm** [_options_] [_prompt_]
34+
35+
# PARAMETERS
36+
37+
**-f** _file_
38+
> Read prompt text from _file_.
39+
40+
**-m**, **--model** _model_
41+
> Use _model_ for this run only.
42+
43+
**--provider** _name_
44+
> Select an installed provider (for example **groq** or **gemini**).
45+
46+
**--system** _text_
47+
> Set the system prompt.
48+
49+
**--temperature**, **--ture** _n_
50+
> Set sampling temperature between **0.0** and **2.0**.
51+
52+
**--max** _n_
53+
> Limit maximum output tokens.
54+
55+
**--session** _id_
56+
> Enable session memory for contextual follow-up prompts.
57+
58+
**--session-window** [_n_]
59+
> Limit how many prior session turns are included (default **10**).
60+
61+
**--stream**, **--no-stream**
62+
> Enable or disable streaming output.
63+
64+
**--chat**
65+
> Start an interactive REPL chat session.
66+
67+
**--dry-run**
68+
> Validate configuration without calling the API.
69+
70+
**--json**, **--pretty**, **--text**, **--raw**
71+
> Control response output format.
72+
73+
**--save**, **--nosave**, **--out** _path_, **--threshold** _bytes_
74+
> Control automatic saving of long responses.
75+
76+
**--refresh-models**, **--list-models**, **--list-providers**
77+
> Manage and inspect provider model lists.
78+
79+
**--set-default** _model_
80+
> Persist the default model for the active provider.
81+
82+
**--install-extras** [_dir_]
83+
> Install optional provider packs, templates, and tools.
84+
85+
**--show-config**, **--diagnostics**
86+
> Print active configuration or run system checks.
87+
88+
**-h**, **--help**
89+
> Show help.
90+
91+
**--version**
92+
> Print version and exit.
93+
94+
# DESCRIPTION
95+
96+
**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.
97+
98+
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.
99+
100+
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.
101+
102+
# CONFIGURATION
103+
104+
**$BASH4LLM_CONFIG_DIR/config**
105+
> Local settings such as model, temperature, max tokens, output format, and save threshold.
106+
107+
**$BASH4LLM_CONFIG_DIR/model.$PROVIDER**
108+
> Persistent default model for a provider.
109+
110+
**$BASH4LLM_CONFIG_DIR/ui_state/**
111+
> Atomic JSON metadata for external tools and optional GUI integrations.
112+
113+
**$BASH4LLM_HISTORY_DIR/sessions/<id>.ndjson**
114+
> Session conversation history when **--session** is enabled.
115+
116+
**GROQ_API_KEY**
117+
> API key for the default Groq provider.
118+
119+
**BASH4LLM_TMPDIR**
120+
> Private temporary directory used instead of system **/tmp**.
121+
122+
Model selection precedence is: **-m/--model**, then **model.$PROVIDER**, then provider auto-selection, then the first whitelisted model, then the legacy global config file.
123+
124+
# CAVEATS
125+
126+
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.
127+
128+
# EXIT CODES
129+
130+
**0**
131+
> Success.
132+
133+
**10**
134+
> Missing API key.
135+
136+
**11**
137+
> Invalid or non-whitelisted model.
138+
139+
**12**
140+
> Network or curl failure.
141+
142+
**14**
143+
> No prompt provided.
144+
145+
**15**
146+
> Filesystem or temporary-file error.
147+
148+
**16**
149+
> Provider HTTP or API error.
150+
151+
# SEE ALSO
152+
153+
[groq](/man/groq)(1), [curl](/man/curl)(1), [jq](/man/jq)(1)
154+
155+
# RESOURCES
156+
157+
```[Source code](https://github.com/kamaludu/bash4llm)```
158+
159+
<!-- verified: 2026-06-28 -->

‎assets/commands/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -628,6 +628,7 @@ basenc.md
628628
bash-completion.md
629629
bash-it.md
630630
bash.md
631+
bash4llm.md
631632
bashbug.md
632633
basher.md
633634
bashmarks.md

0 commit comments

Comments
 (0)