Groq Code CLI 使用指南：打造属于你的轻量级命令行工具

Groq Code CLI 是一个开源、可定制的命令行工具，专为希望快速迭代开发、构建专属工具的程序员打造。它精简、灵活，功能齐全但不臃肿，尤其适合那些想亲自动手、按需扩展功能的开发者。

📌 什么是 Groq Code CLI？

Groq Code CLI 并非只是一个工具，而是一个开发“起点”。它为你提供了一套干净、结构合理的基础框架，让你可以像搭积木一样添加功能、改造界面、定义命令，并与你的开发习惯深度融合。

相比于那些功能庞杂、上手门槛高的 CLI 工具，Groq Code CLI 更像是一张白纸，你可以决定它最终变成什么样子。

特点概览

✅ 极简设计，无冗余代码
🔧 完全可自定义的命令结构
💬 支持与 Groq 模型交互
💡 内置丰富开发接口（hooks / TUI / agent）
🚀 快速开发与测试能力

🧭 安装指南

根据你的需求和使用习惯，Groq Code CLI 支持两种安装方式。

方式一：本地开发模式（推荐）

如果你计划深入定制 CLI 功能，推荐使用开发模式安装：

git clone https://github.com/build-with-groq/groq-code-cli.git
cd groq-code-cli
npm install
npm run build
npm link  # 全局启用 groq 命令

在开发过程中，可以使用自动监听并构建的命令来提高效率：

npm run dev

方式二：快速体验

如果你只是想临时体验一下 Groq CLI，可以用以下方式一键启动：

npx groq-code-cli@latest

🚀 快速上手：如何使用 Groq CLI？

完成安装后，在终端中直接运行：

groq

首次使用时，你需要登录 Groq 平台：

/login

系统会提示你输入 API Key，你可以在 Groq Console 获取。登录成功后，CLI 会在本地创建 .groq/ 配置目录，保存密钥、默认模型等信息。

⚙️ 常用命令选项一览

Groq CLI 启动命令支持多种参数，具体如下：

groq [options]

Options:
  -t, --temperature <temp>      设置生成温度（默认 1）
  -s, --system <message>        自定义系统提示信息
  -d, --debug                   启用调试日志
  -h, --help                    显示帮助信息
  -V, --version                 显示版本号

💡 可用 Slash 命令（斜线命令）

Groq CLI 内置了一些用于操作模型和环境的 slash 命令：

命令	描述
`/help`	查看帮助和所有命令
`/login`	登录并输入 API Key
`/model`	选择使用的 Groq 模型
`/clear`	清空当前会话和上下文
`/reasoning`	是否展示推理内容（开/关）

🧪 本地开发和调试

如果你打算开发自己的工具或命令，可以使用以下方式启动本地开发模式：

npm run dev

这会自动监听源码的改动并重新构建，极大提高迭代效率。

构建项目

npm run build  # 构建 TypeScript 到 dist 目录

📁 项目结构详解

项目结构模块化清晰，以下是主要目录与功能介绍：

groq-code-cli/
├── src/
│   ├── commands/           # 命令定义和注册
│   ├── core/               # CLI 核心逻辑与 Groq Agent
│   ├── tools/              # 扩展工具的实现与注册
│   ├── ui/                 # TUI 交互界面组件
│   └── utils/              # 工具函数与配置
├── docs/                   # 文档与资源
├── package.json            # 项目依赖与配置
└── tsconfig.json           # TypeScript 配置

如果你是第一次阅读代码，建议从以下文件入手：

src/core/cli.ts：命令行程序入口
src/core/agent.ts：模型通信与响应处理
src/ui/hooks/useAgent.ts：TUI 与 Agent 的桥梁

🛠️ 如何添加新功能？

Groq CLI 的核心设计理念之一是“可扩展”。你可以很方便地添加新工具（Tool）或新命令（Command）。

✅ 添加新 Tool（工具）

工具是模型可调用的函数，通常用于处理逻辑或数据。

步骤一：定义工具 schema
在 src/tools/tool-schemas.ts 中添加：

export const YOUR_TOOL_SCHEMA: ToolSchema = {
  type: 'function',
  function: {
    name: 'your_tool_name',
    description: '工具的作用描述',
    parameters: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: '参数说明' }
      },
      required: ['param1']
    }
  }
};

步骤二：实现工具逻辑
在 src/tools/tools.ts 中添加对应函数：

export async function yourToolName(param1: string): Promise<ToolResult> {
  // 实际处理逻辑
  return createToolResponse(true, result, '执行成功');
}

步骤三：注册工具

在 TOOL_REGISTRY 中注册该函数
在 ALL_TOOL_SCHEMAS 数组中添加 schema

✅ 添加新 Slash 命令

Slash 命令是用户与 CLI 直接交互的命令。

步骤一：创建命令定义文件
在 src/commands/definitions/your-command.ts 中添加：

import { CommandDefinition, CommandContext } from '../base.js';

export const yourCommand: CommandDefinition = {
  command: 'yourcommand',
  description: '命令说明',
  handler: ({ addMessage }: CommandContext) => {
    addMessage({
      role: 'system',
      content: '命令返回内容'
    });
  }
};

步骤二：注册命令
在 src/commands/index.ts 中将该命令加入 availableCommands 数组。

🧾 修改启动命令

默认的启动命令是 groq，如果你想改成别的命令（比如 mycli）：

打开 package.json
修改 "bin" 字段中 "groq" 为你想用的新名称
执行以下命令重新构建并全局链接：

npm run build
npm link

🔧 实用小技巧

使用 npm run dev 时，推荐将其跑在后台（或使用 tmux/screen）保持监听状态
通过 .groq/ 目录可以自定义默认模型和运行配置
若多人协作开发建议将工具函数和命令拆分成独立文件维护

🙋 FAQ：你可能关心的问题

💬 Groq CLI 需要联网吗？

是的，它通过 API 与 Groq 模型通信，因此需要互联网连接。

🔐 API Key 安全吗？保存在本地吗？

Groq CLI 会在你的用户主目录下创建 .groq/ 文件夹，本地保存 API Key 和配置文件。建议不要将该文件夹加入 Git 版本控制中。

🛠️ 可以嵌入自己的模型或 API 吗？

当然可以。你可以通过修改 src/core/agent.ts 或添加新的工具逻辑来接入自己的推理服务。

🧪 适合做什么项目？

Groq CLI 最适合用于：

定制化 AI 开发助手
自动化编程工具
代码分析工具集成（如复杂度分析、冗余检测）
组织内部使用的智能命令行工具

🧩 总结：为什么选择 Groq Code CLI？

如果你在寻找一个能轻松上手、快速定制、能陪你构建 AI 助手的 CLI 工具，Groq Code CLI 是一个不错的起点。它没有繁琐的依赖，没有过多干扰，只提供你所需的一切。

你可以把它变成：

团队内部的代码助手
自动文档生成器
CLI 形式的技术支持机器人
甚至是一个 AI 版本的 TUI 工具平台

Groq Code CLI 不只是一个工具，而是一个可塑的框架，等待你去探索。

📎 相关链接

项目地址：https://github.com/build-with-groq/groq-code-cli
Groq Console（获取 API Key）：https://console.groq.com/keys
官方社媒（提交你制作的项目）：https://x.com/GroqInc

Groq Code CLI：打造专属命令行工具的终极指南