From e35005c8f4f8f59f15d0e55243a1ff0b1db73bb0 Mon Sep 17 00:00:00 2001 From: Fechin Date: Fri, 3 Apr 2026 18:30:05 +0800 Subject: [PATCH] feat: add grok-cli and opencode icons, move grok-cli to AI category --- source/_posts/grok-cli.md | 479 ++++++++++++++++++++++++++++++++ source/assets/icon/grok-cli.svg | 1 + source/assets/icon/opencode.svg | 1 + 3 files changed, 481 insertions(+) create mode 100644 source/_posts/grok-cli.md create mode 100644 source/assets/icon/grok-cli.svg create mode 100644 source/assets/icon/opencode.svg diff --git a/source/_posts/grok-cli.md b/source/_posts/grok-cli.md new file mode 100644 index 0000000..71596a4 --- /dev/null +++ b/source/_posts/grok-cli.md @@ -0,0 +1,479 @@ +--- +title: Grok CLI +date: 2026-04-03 14:00:00 +background: bg-[#7c3aed] +tags: + - grok + - xai + - ai + - cli +categories: + - AI +intro: | + [Grok CLI](https://www.grokcli.dev/docs/) is a conversational AI terminal tool powered by X.AI's Grok models, with file operations, code analysis, Plan Mode, and MCP support. +plugins: + - copyCode +--- + +## Getting Started {.cols-3} + +### Quick Start {.row-span-2} + +```bash +# Run immediately (no install) +$ GROK_API_KEY=your_key npx -y grok-cli-hurry-mode@latest + +# Install globally +$ npm install -g grok-cli-hurry-mode@latest + +# Start interactive session +$ grok + +# Send initial message +$ grok "Help me understand this project" + +# Headless / non-interactive mode +$ grok -p "explain the auth module" + +# Use a specific model +$ grok -m grok-4-latest "refactor this file" + +# Set working directory +$ grok -d /path/to/project + +# Set max tool rounds +$ grok --max-tool-rounds 100 "rewrite the API" +``` + +### Authentication + +| Method | How | +| ------------- | ------------------------------------------------- | +| Env variable | `export GROK_API_KEY=your_key` | +| Inline (npx) | `GROK_API_KEY=key npx grok-cli-hurry-mode@latest` | +| CLI flag | `grok --api-key your_key` | +| Settings file | Set `apiKey` in `~/.grok/user-settings.json` | + +Get your API key from [console.x.ai](https://console.x.ai). + +Persist in shell profile: + +```bash +echo 'export GROK_API_KEY=your_key' >> ~/.zshrc +source ~/.zshrc +``` + +### Installation Methods + +| Method | Command | +| ----------------- | ----------------------------------------------------------------------------------------------------- | +| npm (recommended) | `npm install -g grok-cli-hurry-mode@latest` | +| npx (no install) | `npx grok-cli-hurry-mode@latest` | +| yarn | `yarn global add grok-cli-hurry-mode@latest` | +| pnpm | `pnpm add -g grok-cli-hurry-mode@latest` | +| bun | `bun add -g grok-cli-hurry-mode@latest` | +| Auto script | `curl -fsSL https://raw.githubusercontent.com/hinetapora/grok-cli-hurry-mode/main/install.sh \| bash` | + +**Requirements:** Node.js (latest LTS), npm/yarn/pnpm, internet connection. + +### AI Models + +| Model | Description | +| ------------------ | ----------------------------- | +| `grok-code-fast-1` | Default — optimized for code | +| `grok-4-latest` | Latest, enhanced capabilities | +| `grok-3-fast` | Fast, general-purpose | + +Override with `-m`, `GROK_MODEL` env var, or `~/.grok/user-settings.json`. + +Custom base URL: `-u https://api.x.ai/v1` or `GROK_BASE_URL`. + +## CLI Options {.cols-2} + +### All Options {.row-span-2} + +| Option | Alias | Description | +| ----------------------- | ----- | ------------------------------ | +| `--api-key ` | `-k` | Grok API key | +| `--base-url ` | `-u` | API base URL | +| `--model ` | `-m` | Model to use | +| `--prompt ` | `-p` | Headless mode prompt | +| `--directory ` | `-d` | Set working directory | +| `--max-tool-rounds ` | | Max tool rounds (default: 400) | +| `--version` | `-V` | Show version | +| `--help` | `-h` | Show help | + +**Environment variables:** + +| Variable | Purpose | +| --------------- | ------------------- | +| `GROK_API_KEY` | API key (required) | +| `GROK_MODEL` | Default model | +| `GROK_BASE_URL` | Custom API endpoint | + +### Subcommands + +```bash +# AI-generated git commit and push +$ grok git commit-and-push +$ grok git commit-and-push -d /path/to/repo +$ grok git commit-and-push -m grok-4-latest + +# MCP server management +$ grok mcp add +$ grok mcp add-json +$ grok mcp remove +$ grok mcp list +$ grok mcp test +``` + +`git commit-and-push` accepts the same `-d`, `-k`, `-u`, `-m`, `--max-tool-rounds` flags as the main command. + +## Interactive Mode {.cols-3} + +### Keyboard Shortcuts {.row-span-2} + +| Key | Action | +| ----------------- | -------------------------------- | +| `Shift+Tab` twice | Enter Plan Mode | +| `Shift+Tab` | Toggle auto-edit mode | +| `Ctrl+I` | Context tooltip (workspace info) | +| `Ctrl+C` | Clear current input | +| `Esc` | Interrupt current operation | +| `↑` / `↓` | Browse input history | + +{.shortcuts} + +**Auto-edit mode:** Hands-free file editing — the AI edits files without confirmation prompts. + +**Context tooltip (`Ctrl+I`):** Shows project stats, git branch, memory pressure, and session info. + +### Slash Commands + +| Command | Description | +| -------------------- | ----------------------------- | +| `/help` | Show available commands | +| `/clear` | Clear terminal screen | +| `/models` | List available models | +| `/exit` | Quit the application | +| `/compact` | Compress conversation context | +| `/commit-and-push` | AI commit message and push | +| `/init-agent` | Initialize agent docs | +| `/docs` | Open documentation | +| `/readme` | Generate README | +| `/api-docs` | Generate API docs | +| `/changelog` | Generate changelog | +| `/comments` | Add code comments | +| `/update-agent-docs` | Update agent docs | +| `/heal` | Self-healing system check | +| `/guardrails` | Show guardrails status | + +### Config Files + +| File | Purpose | +| ---------------------------- | ---------------------- | +| `~/.grok/user-settings.json` | Global user settings | +| `.grok/settings.json` | Project-level settings | +| `.grok/GROK.md` | Project context for AI | + +**user-settings.json example:** + +```json +{ + "apiKey": "your_api_key", + "model": "grok-code-fast-1", + "baseURL": "https://api.x.ai/v1" +} +``` + +**Create project context:** + +```bash +# Add custom context for Plan Mode +$ mkdir -p .grok +$ echo "# Project Rules" > .grok/GROK.md +``` + +## Tools {.cols-3} + +### Core Tools {.row-span-2} + +| Tool | Purpose | +| --------- | ------------------------------------------ | +| **Read** | Read files — text, images, PDFs, notebooks | +| **Write** | Create or overwrite files | +| **Edit** | Precise string find-and-replace | +| **Bash** | Execute shell commands | +| **Grep** | Regex search via ripgrep | +| **Glob** | File pattern matching | +| **LS** | Directory listing | + +**Read** supports line offset/limit for large files and displays images visually. + +**Edit** supports: + +- Exact string replacement +- Regex patterns +- Single or all-occurrence replacement + +**Bash** supports: + +- stdout/stderr capture +- Background processes +- Timeout management +- Environment variable handling + +### Advanced Tools + +| Tool | Purpose | +| ------------- | ------------------------------------- | +| **MultiEdit** | Atomic multi-file edits with rollback | +| **WebFetch** | Retrieve and parse web content | +| **WebSearch** | Real-time web search | +| **Task** | Delegate to specialized sub-agents | +| **TodoWrite** | Task tracking and progress | + +**MultiEdit** operations: create, edit, delete, rename, move — all in one atomic transaction. + +**Task** (sub-agent delegation): + +- Token-optimized processing +- Complex research and analysis +- Autonomous completion with report + +**WebFetch:** HTML → Markdown conversion with AI content extraction and caching. + +### IDE Tools + +| Tool | Purpose | +| ---------------- | -------------------------------- | +| **NotebookEdit** | Edit Jupyter notebook cells | +| **BashOutput** | Stream background process output | +| **KillBash** | Terminate background processes | + +The AI **automatically selects** the right tool combination for your request — no manual invocation needed. + +## Plan Mode {.cols-3} + +### Activating Plan Mode {.row-span-2} + +Press **`Shift+Tab` twice** in quick succession: + +``` +🎯 Plan Mode: Analysis +📊 Exploring codebase and gathering insights... +``` + +**Or use headless mode:** + +```bash {.wrap} +$ grok -p "analyze changes in this PR and create plan" +$ grok -p "check if changes follow architecture guidelines" +``` + +**What is blocked in Plan Mode:** + +- All file write/edit operations +- Destructive bash commands +- Any state-modifying operations + +**What is allowed:** + +- Reading files (`ls`, `cat`, `grep`) +- Web search and fetch +- Project structure analysis +- Plan generation (writes only to plan output) + +**Exit Plan Mode:** + +- `Enter` — confirm and execute the plan +- `Esc` — exit without executing + +### Plan Mode Phases + +| Phase | Duration | What Happens | +| --------------- | --------------- | -------------------------------- | +| 🔍 Analysis | 1–5 sec | Project type, structure, deps | +| 🧠 Strategy | 5–15 sec | AI generates implementation plan | +| 📋 Presentation | 1–2 sec | Format plan for review | +| ✅ Approval | User-controlled | Review, confirm, or refine | + +{.show-header} + +Plan Mode analyzes: project type (Node/Python/React/etc.), directory structure, key components, dependencies, entry points, modules, and architectural patterns. + +### Plan Mode Tips + +Use Plan Mode for: + +- Complex multi-file features +- Large-scale refactoring +- Exploring unfamiliar codebases +- Risk assessment before changes + +**Tips:** + +- Be specific about what you want +- Review the plan before approving +- Use `/heal` if something breaks +- Create `.grok/GROK.md` for custom context + +## MCP Servers {.cols-2} + +### Managing MCP Servers {.row-span-2} + +```bash +# Add stdio server +$ grok mcp add myserver \ + -t stdio \ + -c npx \ + -a -y my-mcp-package + +# Add HTTP/SSE server +$ grok mcp add myserver \ + -t http \ + -u https://api.example.com/mcp + +# Add with env vars and headers +$ grok mcp add myserver \ + -t http \ + -u https://api.example.com/mcp \ + -e API_KEY=secret \ + -h Authorization="Bearer token" + +# Add from raw JSON +$ grok mcp add-json myserver \ + '{"transport":{"type":"stdio","command":"npx","args":["-y","pkg"]}}' + +# List all servers +$ grok mcp list + +# Test connection +$ grok mcp test myserver + +# Remove a server +$ grok mcp remove myserver +``` + +### MCP Config Schema + +**In `.grok/settings.json`:** + +```json +{ + "mcpServers": [ + { + "name": "my-server", + "transport": { + "type": "stdio", + "command": "npx", + "args": ["-y", "my-mcp-package"], + "env": { "KEY": "value" } + } + }, + { + "name": "remote-server", + "transport": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": { "Authorization": "Bearer $TOKEN" } + } + } + ] +} +``` + +**Transport types:** + +| Type | When to Use | +| ----------------- | -------------------------- | +| `stdio` | Local subprocess (default) | +| `http` | Remote HTTP endpoint | +| `sse` | Server-Sent Events | +| `streamable_http` | Streaming HTTP | + +### Add Server Options + +| Option | Alias | Description | +| -------------------- | ----- | ------------------------------------ | +| `--transport ` | `-t` | stdio / http / sse / streamable_http | +| `--command ` | `-c` | Executable (stdio only) | +| `--args [args...]` | `-a` | Command arguments (stdio only) | +| `--url ` | `-u` | Server URL (http/sse) | +| `--headers [kv...]` | `-h` | HTTP headers (`key=value`) | +| `--env [kv...]` | `-e` | Env vars (`key=value`) | + +## Troubleshooting {.cols-3} + +### Common Issues {.row-span-2} + +**API key not found:** + +```bash +# Verify env var is set +$ echo $GROK_API_KEY + +# Or set inline +$ GROK_API_KEY=key grok "hello" +``` + +**Command not found after install:** + +```bash {.wrap} +# Add npm global bin to PATH +$ echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc +$ source ~/.zshrc +$ which grok +``` + +**Permission errors on install:** + +```bash +# Use sudo (not recommended) or node version manager +$ npm install -g grok-cli-hurry-mode --force + +# Or use nvm/fnm without sudo +$ nvm use --lts +$ npm install -g grok-cli-hurry-mode +``` + +**Stuck / cached installation:** + +```bash +$ pkill -f grok +$ npm uninstall -g grok-cli-hurry-mode +$ npm cache clean --force +$ npm install -g grok-cli-hurry-mode@latest +``` + +### Useful Env Vars + +| Variable | Description | +| --------------- | ---------------------- | +| `GROK_API_KEY` | API key (required) | +| `GROK_MODEL` | Override default model | +| `GROK_BASE_URL` | Custom API endpoint | + +**Default API endpoint:** `https://api.x.ai/v1` + +### Git Smart Push + +The automated release system creates version bump commits, so always use smart push to avoid conflicts: + +```bash +# Correct — handles auto version bumps +$ npm run smart-push +$ git pushup + +# Wrong — causes "fetch first" errors +$ git push origin main +``` + +## Also see {.cols-1} + +- [Official Documentation](https://www.grokcli.dev/docs/) _(grokcli.dev)_ +- [Plan Mode Guide](https://www.grokcli.dev/docs/guides/plan-mode) _(grokcli.dev)_ +- [Tools Overview](https://www.grokcli.dev/docs/tools/overview) _(grokcli.dev)_ +- [Architecture Overview](https://www.grokcli.dev/docs/architecture/overview) _(grokcli.dev)_ +- [GitHub Repository](https://github.com/hinetapora/grok-cli-hurry-mode) _(github.com)_ +- [xAI API Console](https://console.x.ai) _(console.x.ai)_ diff --git a/source/assets/icon/grok-cli.svg b/source/assets/icon/grok-cli.svg new file mode 100644 index 0000000..efb1a61 --- /dev/null +++ b/source/assets/icon/grok-cli.svg @@ -0,0 +1 @@ +Grok \ No newline at end of file diff --git a/source/assets/icon/opencode.svg b/source/assets/icon/opencode.svg new file mode 100644 index 0000000..1c3170d --- /dev/null +++ b/source/assets/icon/opencode.svg @@ -0,0 +1 @@ + \ No newline at end of file