groq-chat

groq-chat is a minimalistic, high-performance command-line interface (CLI) for interacting with Groq AI and other OpenAI compartible models. Written in Go, it provides a fast, resource-efficient one-shot chat experience ideal for developers and AI enthusiasts.

• Tiny Memory usage: 11–14MB
• Small Docker image size: ~9–11MB
• Cross-platform: Windows, Linux, macOS

---

⚡ Quick Overview

• One-shot prompts only — no conversation context is preserved.
• Fast & lightweight — runs even on older hardware.
• Interactive CLI — switch models, view history, and more.
• Response statistics — see token count, completion time, and tokens per second.
• Support for multiple AI providers — works with any OpenAI-compatible API.

---

🚀 Getting Started

🔑 Requirements

• Groq API Key: Sign up here
• (Optional) OpenAI API Key if you want to use OpenAI models, also you can get xAI, OpenRouter, Mistral, etc.
• (Optional) Go 1.18+ if building from source
• (Optional) Docker for containerized usage

📦 Installation via GitHub Releases

1. Visit Releases
2. Download your platform-specific archive
3. Extract and move the binary into your $PATH

   tar -xzf groq-chat-linux-amd64.tar.gz
   mv groq-chat /usr/local/bin/

🐳 Run via Docker

• Pull the latest image

docker pull oleksiyml/groq-chat

• Provide GROQ_API_KEY as an value

docker run --rm -it \
  -e GROQ_API_KEY=your_api_key \
  -v $HOME/.groq-chat:/root/.groq-chat \
  oleksiyml/groq-chat

• Provide GROQ_API_KEY as an env variable

export GROQ_API_KEY=your_api_key

docker run --rm -it \
  -e GROQ_API_KEY=$GROQ_API_KEY \
  -v $HOME/.groq-chat:/root/.groq-chat \
  oleksiyml/groq-chat

See details at Docker hub.

---

💬 Usage

groq-chat

After that you will see:

🍎 One-shot Groq CLI chat
[i]nfo | [m]odel | [u]pdate | [h]istory ([s]ave:%s) | [c]onfig | [q]uit

[model_name] >

The %s placeholder allows for dynamic display of the history saving status (On/Off).

Interactive commands:

• [i] — Show current model info
• [m] — Switch model (up to 20 shown)
• [u] — Update models list from the current provider. Excluded models (part of the names) can be configured in config_<provider>.yaml (see below)
• [h] — Show history - list of the saved answers in Markdown format
• [s] — Toggle history saving (On/Off)
• [c] — Change config (it should be previously saved in config_<provider>.yaml)
• [q] — Quit

One-shot prompts

Examples of good one-shot prompts

Example 1:

You are a DevOps engineer. Explain the best practices for setting up a CI/CD pipeline using Jenkins in 200-300 words.

Example 2:

You are a Linux system administrator. Summarize the key steps to secure a Linux server against common vulnerabilities in 200-300 words.

Example 3:

You are a cloud engineer. Describe the process of deploying a containerized application on Kubernetes, including key commands, in 200-300 words.

Example 4:

You are a network engineer. Summarize how to configure a firewall using `iptables` to allow HTTP and SSH traffic in 200-300 words.

Example 5:

You are a DevOps specialist. Explain how to monitor system performance using `top`, `htop`, and `vmstat` commands in 200-300 words.

Example 6:

You are a Linux user. Summarize how to use `grep` and `awk` together to extract and process log file data in 200-300 words.

Example 7:

You are a system administrator. Describe the steps to automate backups using `rsync` and cron jobs in 200-300 words.

Remember: Each prompt must be fully self-contained.

After receiving a response, you'll see statistics in the format:

───┤ Stats: 31 tokens | 0.02 sec | 1911.78 tok/sec ├───

This shows:

• Total tokens used
• Completion time in seconds
• Tokens per second processing rate

---

⚙️ Configuration

Auto-generated on first run

~/.groq-chat/config.yaml

api_key_name: GROQ_API_KEY
app_title: "\U0001F34E One-shot Groq CLI chat"
base_url: https://api.groq.com/openai/v1
default_model: allam-2-7b
excluded_models:
    - whisper
    - playai
models:
    - allam-2-7b
    - compound-beta
    - compound-beta-mini
    - deepseek-r1-distill-llama-70b
    - gemma2-9b-it
    - llama-3.1-8b-instant
    - llama-3.3-70b-versatile
    - llama3-70b-8192
    - llama3-8b-8192
    - meta-llama/llama-4-maverick-17b-128e-instruct
    - meta-llama/llama-4-scout-17b-16e-instruct
    - meta-llama/llama-guard-4-12b
    - meta-llama/llama-prompt-guard-2-22m
    - meta-llama/llama-prompt-guard-2-86m
    - mistral-saba-24b
    - qwen-qwq-32b
    - qwen/qwen3-32b
provider_name: Groq
save_history: false

• Use GROQ_API_KEY as env variable.
• You canchange any of the values.
• Models list will be updated automatically via [u] command.
• You can exclude some models from the list when updating. Each line is part of the excluded model(s) name
• You can create your own config file and use it with [c] command. (see below)

Note: You can save all your API keys in the ~/.zshrc or ~/.bashrc file.

export GROQ_API_KEY=your_api_key
export OPENAI_API_KEY=your_api_key
export OPENROUTER_API_KEY=your_api_key
export XAI_API_KEY=your_api_key

after that run

source ~/.zshrc

or

source ~/bashrc

to apply changes.

---

Custom providers configurations

Examples of config files

xAI (Grok)

config_grok.yaml

api_key_name: XAI_API_KEY
app_title: "\U0001F680 One-shot Grok-3 CLI chat"
base_url: https://api.x.ai/v1
default_model: grok-3-mini
excluded_models:
    - fast
    - playai
models:
    - grok-3
    - grok-3-mini
provider_name: Grok
save_history: false

OpenAI

config_openai.yaml

api_key_name: OPENAI_API_KEY
app_title: "One-shot OpenAI CLI chat"
base_url: https://api.openai.com
default_model: gpt-4.1-mini
excluded_models:
    - fast
    - 3.5
models:
    - gpt-4.1-mini
    - gpt-4.1
provider_name: OpenAI
save_history: false

OpenRouter

config_openrouter.yaml

api_key_name: OPENROUTER_API_KEY
app_title: "One-shot OpenRouter CLI chat"
base_url: https://openrouter.ai/api/v1
default_model: nvidia/llama-3.3-nemotron-super-49b-v1:free
excluded_models:
    - fast
    - -3.1
models:
    - deepseek/deepseek-chat-v3-0324:free
    - deepseek/deepseek-v3-base:free
    - deepseek/deepseek-r1:free
    - nvidia/llama-3.1-nemotron-ultra-253b-v1:free
    - nvidia/llama-3.3-nemotron-super-49b-v1:free
    - qwen/qwen3-235b-a22b:free
provider_name: OpenRouter
save_history: false

• Use api_key_name as env variable.

Chat history

• The chat history is saved as Markdown files in ~/.groq-chat/history/. Each chat is a separate file, named after the timestamp of the chat creation.
• It can be viewed in any Markdown viewer, nano recommended.
• You can delete them manually

---

🔨 Building from Source

git clone https://github.com/OleksiyM/groq-cli-chat
cd groq-cli-chat
make build

Output will be in bin/groq-chat

Optional:

make build        # Build the binary
make clean        # Clean build artifacts
make release      # Build .zip/.tar.gz archives and binaries
make docker       # Docker image (Debian base) - not implemented yet

---

📁 Project Structure

cmd/
└── main.go/    # Main CLI entry point
internal/
├── chat/       # Chat loop, history
├── config/     # Config management
├── groq/       # API client
resources/      # UI messages, defaults
Dockerfile      # distroless Debian image (~9MB)
Dockerfile.rhel # scratch-based RHEL image
bin/            # Compiled binaries
go.mod          # Go module file
go.sum          # Go module checksum file
Makefile        # Build automation
README.md       # This file

---

✅ Features

• Minimal memory & disk usage
• Clean, interactive CLI
• Configurable via YAML and env vars
• Secure (no API key in source)
• Chat history in Markdown (optional, configured in the settings.yaml)
• Blasing fast
• Crossplatform (Linux, macOS, Windows)
• Response statistics (tokens, time, tokens/sec)
• Support for multiple AI providers (OpenAI compartible APIs)

---

🔭 Roadmap

• Create a CLI interface in Go with an interactive shell
• Save chat history as Markdown files
• Support model selection from a list (up to 10 for now)
• Built-in model information viewer
• Cross-platform releases (.tar.gz, .zip) for Linux, macOS, and Windows
• Compact Docker images based on Debian and RHEL
• Configuration via YAML and GROQ_API_KEY environment variable
• GitHub Actions: automatic build and release publishing
• Response statistics (tokens, time, tokens/sec)
• Support for multiple AI providers (OpenAI-compatible APIs)
• Add toggle for save history to settings.yaml
• Add menu command for tooggle save history
• CI: add unit tests and run go test in GitHub Actions
• Multi-turn chat support
• ANSI color output
• Expand CLI functionality: --config flag, auto-loading models
• Generate simple HTML version of chat history (from .md files)
• CLI command autocompletion for [i], [m], [h], etc., in TUI
• Documentation: add demos (GIFs/SVGs), example prompts
• Publish Docker images to Docker Hub (automatically from CI)
• Separate internal API and UI (prep for SDK/library)

---

🤝 Contributing

Contributions, ideas, and bug reports are welcome. Stay tuned for issue templates and guidelines.

📜 License

MIT License

🙏 Acknowledgments

• Built with Go, Cobra, and Viper
• Powered by Groq
• Inspired by minimalistic CLI tools

---

Made with ❤️ for hackers, devs, DevOps, SysAdmins and prompt-crafters.