Groq CLI Tool

A minimal, production-grade local CLI tool that uses Groq's llama-3.3-70b-versatile model. Designed as a thin client: cloud reasoning, local control.

Constraints & Features

• Model: Strictly llama-3.3-70b-versatile.
• No Local Models: Lightweight, relies on Groq API.
• Linux-First: System prompt enforces Linux assumptions.
• Safe: No automatic command execution.
• Structured: Concise, markdown formatted output.

Installation (One-Click)

To install globally so you can run ai from any folder:

Windows (PowerShell)

Run the install script:

./install_windows.ps1

Linux / WSL

Run the install helper from Windows:

./install_wsl.bat

Or manually inside WSL:

chmod +x install_linux.sh
./install_linux.sh
source ~/.bashrc

Manual Installation

If you prefer to install manually:

pip install .

Note: You may need to manually add your Python Scripts folder to your PATH.

Setup API Key

You must set your API key environment variable:

Windows:

[System.Environment]::SetEnvironmentVariable('GROQ_API_KEY', 'your_key_here', [System.EnvironmentVariableTarget]::User)
# Restart terminal to apply

Linux / WSL:

echo 'export GROQ_API_KEY="your_key_here"' >> ~/.bashrc
source ~/.bashrc

Usage

The tool exposes a single command ai. You can use it with or without quotes.

ai instruction
# or
ai "instruction"

Examples

1. Basic Query:

ai Explain the difference between TCP and UDP headers

2. Coding Help:

ai Write a Python script to recursively list all parsing errors in a log file

3. System Command Execution: You can ask the AI to generate and execute commands for you using the -e (or --execute) flag. The tool will propose a command and ask for your confirmation before running it.

ai -e "Find all files larger than 10MB in /var/log"

Output:

Proposed Command:
find /var/log -type f -size +10M

Execute this command? [y/N]: y
...

Troubleshooting

• Authentication Error: Ensure GROQ_API_KEY is set correctly.
• Rate Limit: The free tier of Groq has limits. Wait a moment and try again.
• Timeout: Requests exceeding 30s may time out.

WSL (Windows Subsystem for Linux) Usage

Since you are strictly using llama-3.3-70b-versatile with Linux-first assumptions, WSL is an ideal environment.

1. Access the directory: Navigate to your cloned repository:

   cd groq-cli

2. Install: We recommend using a virtual environment in WSL to avoid conflicts with apt-managed python.

   python3 -m venv venv
   source venv/bin/activate
   pip install -e .

3. Set API Key:

   export GROQ_API_KEY="gsk_..."

4. Run:

   ai "List the top 5 largest files in the current directory"

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.