{"id":50511345,"url":"https://github.com/lalomorales22/grok-4-cli","last_synced_at":"2026-06-02T20:32:25.623Z","repository":{"id":310164163,"uuid":"1038938303","full_name":"lalomorales22/grok-4-cli","owner":"lalomorales22","description":"Grok-4 CLI, an attempt at giving Grok4 a CLI ","archived":false,"fork":false,"pushed_at":"2025-11-23T03:21:51.000Z","size":86,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-23T05:19:30.773Z","etag":null,"topics":["agent","cli","grok4"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lalomorales22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-16T05:56:55.000Z","updated_at":"2025-11-23T03:21:55.000Z","dependencies_parsed_at":"2025-08-16T07:40:45.451Z","dependency_job_id":null,"html_url":"https://github.com/lalomorales22/grok-4-cli","commit_stats":null,"previous_names":["lalomorales22/grokcli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lalomorales22/grok-4-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalomorales22%2Fgrok-4-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalomorales22%2Fgrok-4-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalomorales22%2Fgrok-4-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalomorales22%2Fgrok-4-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lalomorales22","download_url":"https://codeload.github.com/lalomorales22/grok-4-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalomorales22%2Fgrok-4-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33835766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cli","grok4"],"created_at":"2026-06-02T20:32:21.764Z","updated_at":"2026-06-02T20:32:25.612Z","avatar_url":"https://github.com/lalomorales22.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Grok-4 CLI\n\u003cimg width=\"875\" height=\"487\" alt=\"Screenshot 2025-08-15 at 10 57 03 PM\" src=\"https://github.com/user-attachments/assets/f342b139-72ce-4e63-93f2-a0a19225f2d4\" /\u003e\n\nA professional, feature-rich command-line interface for xAI's Grok API with advanced capabilities similar to Claude Code and Gemini CLI.\n\n[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/yourusername/grok-4-cli)\n[![License](https://img.shields.io/badge/license-ISC-green.svg)](LICENSE)\n[![API](https://img.shields.io/badge/xAI%20API-v1-purple.svg)](https://x.ai/api)\n[![CodeQL](https://github.com/yourusername/grok-4-cli/actions/workflows/codeql.yml/badge.svg)](https://github.com/yourusername/grok-4-cli/actions/workflows/codeql.yml)\n\n## ✨ Features\n\n### 🎨 Enhanced UI Experience\n- **Animated Welcome Screen** with black \u0026 white gradient ASCII art\n- **Rich Terminal Formatting** with syntax highlighting and markdown rendering\n- **Progress Indicators** for streaming responses and long operations\n- **Gradient Themes** for a visually appealing interface (16 themes available)\n- **Interactive Tables** for displaying data and options\n- **Animated Loading Effects** including matrix rain, glitch text, and pulse effects\n- **Clean Response Formatting** with proper spacing after token usage\n\n### 💬 Advanced Chat Capabilities\n- **Interactive Mode** with persistent conversation history\n- **Slash Commands** for quick actions (`/help`, `/model`, `/search`, etc.)\n- **GROK.md Support** for project-specific context\n- **Multi-Model Support** (Grok-4, Grok-3, Grok-3-mini, Grok-2-image)\n- **Streaming Responses** with real-time progress tracking\n- **Session Management** - Save, load, and resume conversations\n\n### 🚀 Unique Grok Features\n- **Live Search Integration** - Search web, news, and X platform in real-time\n- **Image Generation** - Create and auto-save images locally to `./grok-images/`\n- **Vision Analysis** - Analyze images with Grok-4's vision capabilities\n- **Function Calling** - Execute tools for file operations (auto-creates files)\n- **Token Usage Tracking** - Monitor API usage and costs in real-time\n- **Automatic Rate Limit Handling** with exponential backoff\n\n### 🤖 Agentic Capabilities (NEW!)\nInspired by Claude Code, Grok CLI now includes advanced autonomous capabilities:\n\n- **🐚 Enhanced Shell Commands** - Persistent shell sessions with working directory state\n  - Execute commands with `cd` that persists across calls\n  - Background process management for long-running tasks\n  - Real-time streaming output for commands\n  - Configurable timeouts and error handling\n\n- **📋 Task Planning \u0026 Management** - Intelligent task tracking and execution\n  - Break down complex operations into manageable steps\n  - Track task status (pending, in_progress, completed, failed)\n  - Dependency resolution and progress visualization\n  - Export/import task states for reproducibility\n\n- **⚡ Parallel Tool Execution** - Run multiple tools concurrently\n  - Execute up to 5 tools simultaneously\n  - Automatic dependency resolution\n  - Graceful error handling for parallel operations\n  - Sequential and dependency-based execution modes\n\n- **🔗 Tool Chaining** - Build complex multi-step workflows\n  - Chain multiple tools with conditional execution\n  - Process intermediate results with callbacks\n  - Stop on error or continue with fallbacks\n  - Compose reusable operation sequences\n\n**New Slash Commands:**\n- `/shell \u003ccmd\u003e` or `/sh \u003ccmd\u003e` - Execute shell commands\n- `/cwd` or `/pwd` - Show current working directory\n- `/bg` or `/background` - List background processes\n- `/tasks` - View agent task list and progress\n\nSee [AGENT_FEATURES.md](AGENT_FEATURES.md) for detailed documentation.\n\n### 📁 Data Management\n- **Persistent History** - Save and resume conversations\n- **Export Options** - Export to Markdown, JSON, HTML, or plain text\n- **Configuration Management** - Store preferences in `~/.grok-cli/config.json`\n- **Session Management** - Load and continue previous conversations\n- **Secure API Key Storage** - Multiple options including keytar integration\n\n## 📦 Installation\n\n### Quick Setup (Recommended)\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd grok-4-cli\n\n# Run the setup script\n./setup.sh\n\n# Or manually:\nnpm install\nnpm link\n```\n\n### Manual Installation\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd grok-4-cli\n\n# Install dependencies\nnpm install\n\n# Copy environment template\ncp .env.example .env\n\n# Link CLI globally (optional)\nnpm link\n```\n\n### Required Dependencies\n\nThe CLI uses the following packages (automatically installed via `npm install`):\n\n- **Core Functionality**\n  - `openai` - API client (OpenAI-compatible)\n  - `commander` - CLI framework\n  - `dotenv` - Environment variable management\n  - `axios` - HTTP client\n\n- **UI \u0026 Animations**\n  - `chalk` - Terminal styling\n  - `ora` - Loading spinners\n  - `figlet` - ASCII art text\n  - `gradient-string` - Gradient text effects\n  - `boxen` - Terminal boxes\n  - `cli-progress` - Progress bars\n  - `cli-table3` - Formatted tables\n\n- **Interactive Features**\n  - `inquirer` - Interactive prompts\n  - `readline` - Terminal input\n\n- **Data \u0026 Configuration**\n  - `fs-extra` - Enhanced file system operations\n  - `conf` - Configuration management\n\n- **Content Processing**\n  - `marked` - Markdown parsing\n  - `marked-terminal` - Terminal markdown rendering\n  - `cli-highlight` - Syntax highlighting\n  - `highlight.js` - Code highlighting\n\n## 🔧 Configuration\n\n### First-Time Setup (Automatic)\n\nWhen you run the CLI for the first time without an API key, it will automatically start the setup wizard:\n\n```bash\ngrok\n# Setup wizard will guide you through getting and saving your API key\n```\n\n### Getting Your xAI API Key\n\n1. **Visit**: [https://console.x.ai](https://console.x.ai)\n2. **Sign in** with your X (Twitter), Google, or xAI account\n3. **Navigate to** \"API Keys\" section\n4. **Click** \"Create API Key\" button\n5. **Name** your key (e.g., \"grok-cli\")\n6. **Copy** the generated key (starts with `xai-`)\n\n### API Key Setup Options\n\n1. **Setup Wizard** (Recommended)\n   ```bash\n   grok config\n   # Select \"Run setup wizard\"\n   ```\n\n2. **Environment Variable**\n   ```bash\n   export XAI_API_KEY=\"xai-your-key-here\"\n   ```\n\n3. **Local .env File**\n   ```bash\n   echo \"XAI_API_KEY=xai-your-key-here\" \u003e .env\n   ```\n\n4. **Secure Config Storage**\n   ```bash\n   grok config\n   # Select \"Set/Change API key\"\n   ```\n\nThe CLI checks for API keys in this order:\n1. Environment variable (`XAI_API_KEY`)\n2. Config file (`~/.config/grok-cli/`)\n3. Local `.env` file\n\n### Project Context (GROK.md)\n\nCreate a `GROK.md` file in your project root to provide context:\n\n```markdown\n# GROK.md\nProject-specific instructions and context for Grok...\n```\n\n## 🎮 Usage\n\n### Interactive Mode\n\nStart an interactive chat session with all features enabled:\n\n```bash\ngrok\n# Function calling is enabled by default\n# Grok can create, read, and modify files automatically\n```\n\n### Slash Commands in Interactive Mode\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show all available commands |\n| `/model` | Switch between Grok models |\n| `/clear` | Clear current conversation |\n| `/save` | Save conversation to history |\n| `/load` | Load previous conversation |\n| `/history` | View saved conversations |\n| `/search` | Configure Live Search mode |\n| `/image \u003cprompt\u003e` | Generate an image |\n| `/vision` | Analyze an image |\n| `/tools` | Toggle function calling |\n| `/config` | Configure settings |\n| `/export` | Export conversation |\n| `/tokens` | Show token usage |\n| `/exit` | Exit the CLI |\n\n### Command Line Mode\n\n#### Basic Chat\n```bash\ngrok chat \"What is quantum computing?\"\n```\n\n#### With Options\n```bash\ngrok chat \"Explain AI\" --model grok-3-mini --stream --temperature 0.7\n```\n\n#### Image Generation\n```bash\ngrok image \"A cyberpunk city at night\" --number 2\n# Images are automatically saved to ./grok-images/\n```\n\n#### Vision Analysis\n```bash\ngrok vision ./photo.jpg \"What objects are in this image?\"\n```\n\n#### Live Search\n```bash\ngrok search \"Latest AI developments\" --source web --country US\n```\n\n#### Configuration\n```bash\ngrok config\n```\n\n## 🛠️ Advanced Features\n\n### Live Search Integration\n\nEnable real-time search across multiple sources:\n\n```javascript\n// In interactive mode\n/search\n// Select mode: auto, on, or off\n\n// Command line\ngrok search \"query\" --source web|news|x\n```\n\n### Function Calling\n\nThe CLI includes built-in tools for file operations:\n- Read files\n- Write/Create files (automatic - no approval needed)\n- Edit files\n- List directories\n- Execute commands\n- Make HTTP requests\n\nFile creation is automatic to enable AI assistance with coding tasks. Other operations follow approval workflow:\n- `suggest` mode: Ask for approval for operations (except file creation)\n- `auto-edit` mode: Auto-approve edits, ask for others\n- `full-auto` mode: Execute all operations automatically\n\n### Export Formats\n\nExport conversations in multiple formats:\n\n```bash\n# In interactive mode\n/export\n\n# Formats available:\n- Markdown (.md)\n- JSON (.json)\n- HTML (.html) - Beautiful styled output\n- Plain Text (.txt)\n```\n\n## 📊 Token Usage \u0026 Cost Tracking\n\nThe CLI automatically tracks token usage and calculates costs:\n\n```\n📊 Tokens: 1,234 (Input: 234, Output: 1,000)\n💰 Cost: $0.003234\n```\n\n### Pricing (as of 2025)\n\n| Model | Input (per 1M tokens) | Output (per 1M tokens) |\n|-------|----------------------|------------------------|\n| Grok-4 | $3.00 | $15.00 |\n| Grok-3 | $3.00 | $15.00 |\n| Grok-3-mini | $0.30 | $0.50 |\n| Grok-2-image | - | $0.07 per image |\n\n## 🎨 Themes \u0026 Customization\n\nThe CLI supports multiple gradient themes:\n- `cyberpunk` (default)\n- `matrix`\n- `sunset`\n- `ocean`\n- `fire`\n- `rainbow`\n\nChange theme in config:\n```bash\ngrok config\n# Select \"Theme\"\n```\n\n## 📁 File Structure\n\n```\n~/.grok-cli/\n├── config.json          # User configuration\n└── history/            # Saved conversations\n    └── session-*.json\n\n./grok-exports/         # Exported conversations\n├── *.md\n├── *.json\n├── *.html\n└── *.txt\n\n./grok-images/          # Generated images (auto-created)\n└── grok-image-*.png\n```\n\n## 🔒 Security\n\n- API keys are never hardcoded\n- Approval workflow for file operations\n- Secure configuration storage\n- Input sanitization\n- Rate limit handling with exponential backoff\n\nFor responsible disclosure, see SECURITY.md. Use `.env` (ignored by Git) or environment variables for secrets. Enable debug logging by setting `DEBUG=true`.\n\n## 🧰 GitHub Project Hygiene\n\n- `.gitignore` excludes secrets, logs, caches, and local artifacts\n- `.gitattributes` enforces LF endings and marks binaries\n- Code scanning via CodeQL workflow\n- LICENSE included (ISC)\n\n## 🚀 Performance\n\n- 6-minute timeout for reasoning models\n- Streaming support for real-time responses\n- Efficient token management\n- Automatic retry on rate limits\n- Progress indicators for long operations\n\n## 📖 API Documentation\n\nFor detailed API information, see:\n- [xAI API Documentation](https://docs.x.ai)\n- [API Pricing](https://x.ai/api)\n- `grok-api-docs.md` in this repository\n\n## 🏗️ Project Structure\n\n```\ngrok-4-cli/\n├── grok                    # Main CLI executable\n├── grok.backup            # Original CLI backup\n├── lib/                   # Utility modules\n│   ├── tools.js          # Tool execution \u0026 approval workflow\n│   ├── animations.js     # UI animations \u0026 effects\n│   └── export.js         # Export functionality\n├── package.json          # Dependencies \u0026 metadata\n├── README.md            # Documentation\n├── GROK.md             # Project context file\n├── grok-api-docs.md    # API reference\n├── grok4-project.txt   # Project specification\n└── .env                # API key (create this)\n```\n\n## 🔧 Development\n\n### Running from Source\n\n```bash\n# Run directly without global install\nnode grok\n\n# Or make executable\nchmod +x grok\n./grok\n```\n\n### Adding New Features\n\n1. **New Tools**: Add to `lib/tools.js` TOOL_DEFINITIONS\n2. **New Commands**: Add to `processSlashCommand()` in main file\n3. **New Themes**: Add to `lib/animations.js` THEMES object\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Open a Pull Request\n\n## 📄 License\n\nISC License - see LICENSE file for details\n\n## 🙏 Acknowledgments\n\n- Built with the xAI Grok API\n- Inspired by Claude Code and Gemini CLI\n- Powered by Node.js and the amazing open-source community\n\n## 📞 Support\n\nFor issues, questions, or suggestions:\n- Open an issue on GitHub\n- Contact via X/Twitter: @yourusername\n\n---\n\n**Made with ❤️ for the AI community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalomorales22%2Fgrok-4-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flalomorales22%2Fgrok-4-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalomorales22%2Fgrok-4-cli/lists"}