Bash4LLM⁺：セキュアな Bash 優先 AI CLI ツール

Bash4LLM⁺ は、Groq の OpenAI 互換 API と対応し、他社プロバイダーへも拡張可能な、完全に監査可能なラッパー CLI ツールです。単一の Bash スクリプトで構成されるため、自己完結型かつ即座に利用できます。

特徴と利点

• 動的モデルリスト — ハードコードなし。

  GET https://api.groq.com/openai/v1/models

  をリアルタイムで取得します。
• セキュリティバイデザイン —

  /tmp

  使用禁止、

  eval

  禁止、厳格なパーミッション設定を標準実装しています。
• プラットフォーム互換性 — Linux、macOS、WSL、Cygwin、Termux（Android）、BSD で動作が保証されます。
• UI ステートシステム（ui_state） — コアから JSON フォーマットの原子形メタデータを公開し、GUI や Home Assistant などの連携を支援します。
• ストリーミング対応 — リアルタイム出力または終了時の完全出力を切り替え可能です。
• 自動保存機能 — 設定可能な閾値を超えた長文出力を自動的に保存します。
• 高度なモデル管理 — リフレッシュ、リスト表示、デフォルト永続化、動的ホワイトリストを備えています。
• Termux / Android 向け最適化 — Termux を検出し、Android の SELinux/Kernel レstrictions に合わせた堅牢なディレクトリロックへ切り替えます。

脅威モデルとセキュリティ要件

Bash4LLM⁺ は主に シングルユーザー環境（PC、個人サーバー） 向けに設計されています。

セキュリティの前提条件

• プロバイダー信頼性: プロバイダーはシェル内で実行されるコードのため、管理可能な信頼できるディレクトリに配置してください。
• 設定の信頼:

  BASH4LLM_EXTRAS_DIR

  や

  BASH4LLM_TMPDIR

  などの環境変数は管理下にある前提です。
• スクリプトの安全性: スクリプトはモデルからの出力を決して（jamais）実行しません。
• リスク緩和: TOCTOU（Time-of-Check-to-Time-of-Use）や JSON/SSE パースの限界については緩和済みですが、詳細は「SECURITY」セクションで確認してください。

必須要件

PATH 上に以下のパッケージ（または同等品）が存在する必要があります：

• bash

• coreutils

• findutils

• util-linux

• gawk

• curl

• jq

インストール手順

【ファストフォワード】迅速インストールガイド

以下のコマンドを実行して、即座に Bash4LLM⁺ を開始できます。

# 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

API キー設定: スクリプトが Groq の API キー入力を促します。以下の通りエクスポートしてください。

export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxx"

オプション：Extras のインストール

追加プロバイダー（Gemini, Hugging Face など）やテンプレートを含む機能をインストールするには：

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

または、簡易オプションを使用する場合：

./bash4llm --install-extras

選択的なインストール

特定の機能のみをインストールする場合（例：プロバイダー A のみ）：

./bash4llm --install-extras providerA

各種有効フラグ:

• --source <dir>

  : ソースディレクトリ指定

• --force

  : 強制実行

• --dry-run

  : 実行前確認

簡易使用法

プロンプトの入力方法

./bash4llm "イタリア語で短い詩を書いて"

bash<br>./bash4llm <<'EOF'<br>イタリア語で短い詩を書こう<br>EOF</br>

echo "相対性理論を説明して" | ./bash4llm

./bash4llm --dry-run "こんにちは"

./bash4llm -m llama-3.3-70b-versatile "短いエッセイを書いて"

./bash4llm --provider gemini "これを翻訳して"

セッション管理 (

--session

)

コンテキストメモリ（会話履歴）を利用するには、

--session <id>

# 新セッションを開始
./bash4llm --session chat1 "こんにちは"

# 同じセッションで続きを指示
./bash4llm --session chat1 "私が言ったことを要約して"
./bash4llm --session chat1 --session-window 10 "続きを続けて"

⚠️ 重要: コンテキストメモリを利用するには、必ず

--session <id>

コマンドラインオプション詳細

モデルとプロバイダー

--refresh-models

--list-models

--list-models-raw

--list-providers

--set-default <model>

-m

--model <model>

--provider <name>

入力処理

-f <file>

--json-input <json>

--template <name>

--batch <file>

セッション・パラメータ

--session <id>

--init-session

--session

--system <text>

-t

--temperature <n>

--max <n>

出力と保存

--save

--nosave

--out <path>

--threshold <n>

--json

--pretty

--text

実行モード・診断

--dry-run

--quiet

--stream

--no-stream

--chat

--show-config

--diagnostics

設定とモデル優先順位

構成ファイルとパス

• ローカルパラメータ:

  $BASH4LLM_CONFIG_DIR/config

  (MODEL, TURE, MAX_TOKENS など)
• プロバイダー別デフォルト:

  $BASH4LLM_CONFIG_DIR/model.$PROVIDER

• モデルホワイトリスト:

  $MODELS_FILE

  (

  --refresh-models

  で更新)

モデル選択の優先順位

1. -m/--model

   (引数優先)

2. model.$PROVIDER

   (プロバイダー別設定)
3. プロバイダー自動選択 (

   auto_select_model_...

   )
4. ホワイトリスト最初要素 (

   models.txt

   )
5. レガシーグローバル構成 (

   MODEL=...

   )

ファイルセキュリティと隔離

• /tmp

  の使用は禁止されており、一時ファイルは

  $RUN_TMPDIR

  に隔離されます。
• パーミッション:
  • 一時ファイルディレクトリ:

    700

    (umask 077)
  • 保存されたファイル:

    600

• --out

  を指定した場合は、可能な限りディレクトリを作成します。

UI ステートシステム (ui_state)

Bash4LLM⁺ は GUI や外部ツールとの連携を支援するため、原子形 JSON ファイルを提供します。

sessions/<id>.json

active

msg_count

last_ts

sessions/index.json

last_api.json

http_status

req_id

last_history.json

provider_capabilities.json

使い方: GUI（オプション Extras）はこれらのファイルを参照して状態を表示します。CGI プレースホルダーとしても利用可能です。

セキュリティに関する注記

• eval 不使用: スクリプト内で

  eval

  は使用しません。
• 実行不可: モデルの出力をシェルとして実行しません。
• プロバイダー管理: プロバイダーはコードであるため、

  extras

  や

  providers

  ディレクトリを安全に保ってください。
• TOCTOU リスク緩和: Time-of-Check-to-Time-of-Use 問題は緩和済みです。

エラーコード一覧

0

10

BASH4LLM_ERR_NO_API_KEY

11

BASH4LLM_ERR_BAD_MODEL

12

BASH4LLM_ERR_CURL_FAILED

14

BASH4LLM_ERR_NO_PROMPT

15

BASH4LLM_ERR_TMP

16

BASH4LLM_ERR_API

主要な環境変数

GROQ_API_KEY

BASH4LLM_TMPDIR

BASH4LLM_CONFIG_DIR

BASH4LLM_HISTORY_DIR

MODEL

PROVIDER

ALLOWED_MODELS

ライセンス・ライセンスファイル

Bash4LLM⁺ は GPL v3 ライセンスの下で提供されます。詳細は

LICENSE

お問い合わせ

• 著者: Cristian Evangelisti
• メール:

  opensource@cevangel.anonaddy.me

• リポジトリ: https://github.com/kamaludu/bash4llm