Bash4LLM⁺ 使用教程：用纯 Bash 脚本优雅调用 LLM API

原创。手把手教你安装配置 Bash4LLM⁺，用纯 Bash 脚本在终端中调用 LLM API，无需任何运行时依赖。

为什么要用 Bash 调用 LLM？

过去一年，调用 LLM API 的工具越来越多：Python 的 openai 库、Node.js 的 langchain、甚至各种 GUI 客户端。但这些方案都有一个共同的前提——你需要在机器上安装对应的运行时环境。

如果你只是想在终端里快速问一下 LLM，不想装 Python 包、不想初始化 npm 项目，或者你的工作环境是服务器上最小化的 Linux 发行版，Bash4LLM⁺ 就是一个非常优雅的解决方案。

它是一个纯 Bash 脚本，单个文件、自包含、可审计。下载后加执行权限、设好 API Key，立刻就能用。

Bash4LLM⁺ 是什么？

Bash4LLM⁺（读作 "bash for LLM plus"）是 GitHub 上的一个开源项目，由开发者 kamaludu 创建。它本质上是一个对 OpenAI 兼容的 Chat Completions API 的 Bash 封装器，目前默认支持 Groq 的 API（可以扩展到其他提供商）。

它的核心设计理念是：

• 安全优先：不使用 /tmp 存储临时数据，不使用 eval，权限管理严格
• 零依赖：只需要标准 Linux 工具（bash、curl、jq 等），不需要 Python、Node.js 或任何运行时
• 可审计：整个逻辑就是单个 Bash 脚本，你可以逐行阅读和理解它的每个行为
• 跨平台：支持 Linux、macOS、WSL、Termux（Android）、BSD

安装步骤

前置条件

确保你的系统已安装以下工具：

bash coreutils findutils util-linux gawk curl jq

在 Ubuntu/Debian 上：

sudo apt install bash coreutils findutils util-linux gawk curl jq

在 macOS 上（通过 Homebrew）：

brew install coreutils findutils util-linux gawk jq

下载与安装

# 1. 克隆仓库（浅克隆，只取最新提交）
git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm
 
# 2. 创建工作目录并复制可执行文件
mkdir -p bash4llm
cp repo-bash4llm/bin/bash4llm bash4llm/
chmod +x bash4llm/bash4llm
 
# 3. 进入目录并刷新模型列表
cd bash4llm
./bash4llm --refresh-models

首次运行 --refresh-models 时，脚本会提示你输入 Groq API Key：

Enter API key for provider groq (env GROQ_API_KEY):

输入你的密钥后，建议将其设为环境变量，避免每次都要手动输入：

export GROQ_API_KEY="gsk_你的API密钥"

可以将这行添加到 ~/.bashrc 或 ~/.zshrc 中，以便持久化。

安装可选扩展

Bash4LLM⁺ 支持通过 Extras 机制添加额外功能：

./bash4llm --install-extras ../repo-bash4llm/extras/

这可以安装其他提供商的驱动（如 Gemini、Hugging Face、Mistral）、模板、文档和安全工具。

基本用法

最简单的提问

./bash4llm "用中文写一首关于春天的短诗"

多行输入

./bash4llm <<'EOF'
解释一下什么是 RESTful API，
以及它和 GraphQL 的主要区别。
用中文回答。
EOF

查看可用模型

./bash4llm --list-models

这会动态从 Groq API 获取最新的模型列表，而不是硬编码在脚本中。

指定模型

./bash4llm --model llama-3.3-70b-versatile "用 bash 写一个文件监控脚本"

流式输出 vs 完整输出

Bash4LLM⁺ 同时支持流式和非流式模式。流式模式下，LLM 的回答会实时逐 token 显示在终端上，体验就像在 ChatGPT 网页上看到文字一个个蹦出来：

# 流式输出（默认）
./bash4llm --stream "写一段关于 bash 脚本的幽默说明"
 
# 非流式（等待完整响应后一次性输出）
./bash4llm --no-stream "写一段关于 bash 脚本的幽默说明"

自动保存长输出

当回答超过一定长度时，Bash4LLM⁺ 会自动将输出保存到文件，方便后续查看和处理。这个阈值是可以配置的。

设置默认模型

如果每次都要指定 --model 很麻烦，可以设置持久化默认模型：

./bash4llm --set-default-model llama-3.3-70b-versatile

设置后，后续调用不再需要 --model 参数。

进阶用法

自定义 Provider

Bash4LLM⁺ 的设计是可扩展的。除了默认的 Groq，你可以添加其他兼容 OpenAI API 的提供商。Extras 目录中已经包含了 Gemini、Hugging Face、Mistral 等提供商的配置文件。

安装 Extras 后：

# 切换到其他提供商
./bash4llm --provider gemini "对比一下 Bash 和 Python 在文本处理上的优劣"
 
# 列出当前可用的提供商
./bash4llm --list-providers

每个 Provider 本质上是一个 Bash 脚本，放在安全的目录中。脚本负责处理认证、请求构建和响应解析。因为是纯 Bash，你可以完全理解和修改它。

UI State 系统

这是一个比较独特的功能：Bash4LLM⁺ 的核心模块会持续暴露元数据，以 JSON 格式输出。这意味着你可以将其整合到 GUI 工具或 Home Assistant 等外部系统中。

例如，你可以写一个简单的 HTML 仪表盘，实时显示当前正在使用的模型、请求状态、响应时间等信息。

批处理与自动化

由于是纯 CLI 工具，Bash4LLM⁺ 非常适合嵌入到自动化脚本中：

#!/bin/bash
# 批量翻译文件中的英文文本到中文
for file in ./en_docs/*.md; do
  content=$(cat "$file")
  ./bash4llm "将以下英文文档翻译为中文，保持 Markdown 格式：${content}" -o "./zh_docs/$(basename "$file")"
done

安全模型

Bash4LLM⁺ 的安全设计值得单独说几点：

1. 不执行模型输出：脚本永远不会执行模型返回的内容。它只是显示或保存文本
2. 不用 /tmp：临时数据存储在用户指定的安全目录中
3. 不用 eval：这意味着恶意构造的输入也无法通过 eval 执行任意代码
4. Provider 隔离：第三方 Provider 代码必须放在你拥有的安全目录中，且不会自动加载未配对的 Provider
5. 权限限制：脚本文件的权限管理严格，避免其他用户篡改

当然，任何 Bash 脚本都无法完全免疫 TOCTOU（Time-of-Check Time-of-Use）类的竞态条件攻击，但开发者已经在文档中诚实记录了这些风险及其缓解措施。

适用场景

最适合的人群

• 系统管理员：服务器上只有最小化环境，不想为调用 LLM 装一堆依赖
• 终端重度用户：习惯在终端完成所有操作，不想切到浏览器或 GUI
• 自动化需求者：需要将 LLM 调用集成到 Shell 脚本或 cron job 中
• 安全敏感用户：希望看到底层代码做了什么，不想引入黑盒依赖

不太适合的场景

• 需要复杂 Prompt 工程（多轮对话、Function Calling 等高级特性）
• 需要完整的 SDK 支持（错误重试、速率限制、流式解析等工业级能力）
• 非 Unix 环境（Windows 原生不支持）

总结

Bash4LLM⁺ 是一个精巧的工具——它没有试图和大厂 SDK 竞争功能完整性，而是聚焦在一个小而美的场景：在终端中快速、安全地调用 LLM。

它的核心价值在于：

• 零运行时依赖：只要机器有 bash、curl 和 jq，就能跑
• 安全透明：单脚本设计让代码审计变得极其简单
• Unix 哲学：做一件事，把它做好，然后通过管道和脚本组合

如果你是一个经常在终端里工作的开发者或系统管理员，不妨试试把它加入你的工具箱。

项目地址：github.com/kamaludu/bash4llm 许可证：GPLv3