<h2 align="center"> <br> <img src="docs/thumbnail.png" alt="Groq Code CLI" width="400"> <br> <br> Groq Code CLI: A highly customizable, lightweight, and open-source coding CLI powered by Groq for instant iteration. <br> </h2>
npm install groq-code-cli
Overview •
Installation •
Usage •
Development
https://github.com/user-attachments/assets/5902fd07-1882-4ee7-825b-50d627f8c96a
Coding CLIs are everywhere. The Groq Code CLI is different. It is a blueprint, a building block, for developers looking to leverage, customize, and extend a CLI to be entirely their own. Leading open-source CLIs are all fantastic, inspiring for the open-source community, and hugely rich in features. However, that's just it: they are gigantic. Feature-rich: yes, but local development with such a large and interwoven codebase is unfriendly and overwhelming. This is a project for developers looking to dive in.
Groq Code CLI is your chance to make a CLI truly your own. Equipped with all of the features, tools, commands, and UI/UX that’s familiar to your current favorite CLI, we make it simple to add new features you’ve always wanted. By massively cutting down on bloat and code mass without compromising on quality, you can jump into modifying this CLI however you see fit. By leveraging models on Groq, you can iterate even faster (/models to see available models). Simply activate the CLI by typing groq in your terminal. Use Groq Code CLI in any directory just like you would with any other coding CLI. Use it in this directory to have it build and customize itself!
A few customization ideas to get started:
- New slash commands (e.g. /mcp, /deadcode, /complexity, etc.)
- Additional tools (e.g. web search, merge conflict resolver, knowledge graph builder, etc.)
- Custom start-up ASCII art
- Change the start-up command
- Anything you can think of!
bash
git clone https://github.com/build-with-groq/groq-code-cli.git
cd groq-code-cli
npm install
npm run build
npm link # Enables the groq command in any directory
``bash
Run this in the background during development to automatically apply any changes to the source code
npm run dev
`$3
`bash
npx groq-code-cli@latest
`Usage
`bash
Start chat session
groq
`$3
`bash
groq [options]Options:
-t, --temperature Temperature for generation (default: 1)
-s, --system Custom system message
-d, --debug Enable debug logging to debug-agent.log in current directory
-h, --help Display help
-V, --version Display version number
`$3
On first use, start a chat:
`bash
groq
`And type the
/login command:!Login
>Get your API key from the Groq Console here
This creates a .groq/ folder in your home directory that stores your API key, default model selection, and any other config you wish to add.
You can also set your API key for your current directory via environment variable:
`bash
export GROQ_API_KEY=your_api_key_here
`$3
- /help - Show help and available commands
- /login - Login with your credentials
- /model - Select your Groq model
- /clear - Clear chat history and context
- /reasoning - Toggle display of reasoning content in messages
Development
$3
`bash
Run this in the background during development to automatically apply any changes to the source code
npm run dev
`$3
`bash
npm run build # Build TypeScript to dist/
npm run dev # Build in watch mode
`$3
`
groq-code-cli/
├── src/
│ ├── commands/
│ │ ├── definitions/ # Individual command implementations
│ │ │ ├── clear.ts # Clear chat history command
│ │ │ ├── help.ts # Help command
│ │ │ ├── login.ts # Authentication command
│ │ │ ├── model.ts # Model selection command
│ │ │ └── reasoning.ts # Reasoning toggle command
│ │ ├── base.ts # Base command interface
│ │ └── index.ts # Command exports
│ ├── core/
│ │ ├── agent.ts # AI agent implementation
│ │ └── cli.ts # CLI entry point and setup
│ ├── tools/
│ │ ├── tool-schemas.ts # Tool schema definitions
│ │ ├── tools.ts # Tool implementations
│ │ └── validators.ts # Input validation utilities
│ ├── ui/
│ │ ├── App.tsx # Main application component
│ │ ├── components/
│ │ │ ├── core/ # Core chat TUI components
│ │ │ ├── display/ # Auxiliary components for TUI display
│ │ │ └── input-overlays/ # Input overlays and modals that occupy the MessageInput box
│ │ └── hooks/
│ └── utils/
│ ├── constants.ts # Application constants
│ ├── file-ops.ts # File system operations
│ ├── local-settings.ts # Local configuration management
│ └── markdown.ts # Markdown processing utilities
├── docs/
├── package.json
├── tsconfig.json
└── LICENSE
`TL;DR: Start with
src/core/cli.ts (main entry point), src/core/agent.ts, and src/ui/hooks/useAgent.ts (bridge between TUI and the agent). Tools are in src/tools/, slash commands are in src/commands/definitions/, and customize the TUI in src/ui/components/.$3
#### Adding New Tools
Tools are AI-callable functions that extend the CLI's capabilities. To add a new tool:
1. Define the tool schema in
src/tools/tool-schemas.ts:
`typescript
export const YOUR_TOOL_SCHEMA: ToolSchema = {
type: 'function',
function: {
name: 'your_tool_name',
description: 'What your tool does',
parameters: {
type: 'object',
properties: {
param1: { type: 'string', description: 'Parameter description' }
},
required: ['param1']
}
}
};
`2. Implement the tool function in
src/tools/tools.ts:
`typescript
export async function yourToolName(param1: string): Promise {
// Your implementation here
return createToolResponse(true, result, 'Success message');
}
`3. Register the tool in the
TOOL_REGISTRY object and executeTool switch statement in src/tools/tools.ts.4. Add the schema to
ALL_TOOL_SCHEMAS array in src/tools/tool-schemas.ts.#### Adding New Slash Commands
Slash commands provide direct user interactions. To add a new command:
1. Create command definition in
src/commands/definitions/your-command.ts:
`typescript
import { CommandDefinition, CommandContext } from '../base.js';export const yourCommand: CommandDefinition = {
command: 'yourcommand',
description: 'What your command does',
handler: ({ addMessage }: CommandContext) => {
// Your command logic here
addMessage({
role: 'system',
content: 'Command response'
});
}
};
`2. Register the command in
src/commands/index.ts by importing it and adding to the availableCommands array.#### Changing Start Command
To change the start command from
groq, change "groq" in "bin" of package.json to your global command of choice.Re-run
npm run build and npm link`.Improvements through PRs are welcome!
For issues and feature requests, please open an issue on GitHub.
#### Share what you create with Groq on our socials!