FrogCLI

AI-powered command-line workflow tool for developers

Installation • Quick Start • Features • Documentation • Contributing

FrogCLI is a powerful command-line AI workflow tool adapted from Gemini CLI and Qwen Code. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.

💡 Getting Started

FrogCLI supports various AI model providers. You can use OpenAI-compatible APIs with your preferred model provider.

For detailed setup instructions, see Authorization.

[!WARNING] Token Usage Notice: FrogCLI may issue multiple API calls per cycle, resulting in higher token usage. We're actively optimizing API efficiency.

Key Features

• Code Understanding & Editing - Query and edit large codebases beyond traditional context window limits
• Workflow Automation - Automate operational tasks like handling pull requests and complex rebases
• Enhanced Parser - Optimized parser for better code understanding
• Vision Model Support - Automatically detect images in your input and seamlessly switch to vision-capable models for multimodal analysis

Installation

Prerequisites

Ensure you have Node.js version 20 or higher installed.

curl -qL https://www.npmjs.com/install.sh | sh

Install from npm

npm install -g @frogcli/frogcli@latest
frog --version

Install from source

git clone https://github.com/colygon/frogcli.git
cd frogcli
npm install
npm install -g .

VS Code Extension

In addition to the CLI tool, FrogCLI also provides a VS Code extension that brings AI-powered coding assistance directly into your editor with features like file system operations, native diffing, interactive chat, and more.

📦 The extension is currently in development. For installation, features, and development guide, see the VS Code Extension README.

Quick Start

# Start FrogCLI
frog

# Example commands
> Explain this codebase structure
> Help me refactor this function
> Generate unit tests for this module

Session Management

Control your token usage with configurable session limits to optimize costs and performance.

Configure Session Token Limit

Create or edit .frog/settings.json in your home directory:

{
  "sessionTokenLimit": 32000
}

Session Commands

• /compress - Compress conversation history to continue within token limits
• /clear - Clear all conversation history and start fresh
• /stats - Check current token usage and limits

📝 Note: Session token limit applies to a single conversation, not cumulative API calls.

Vision Model Configuration

FrogCLI includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. This feature is enabled by default - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.

Skip the Switch Dialog (Optional)

If you don't want to see the interactive dialog each time, configure the default behavior in your .frog/settings.json:

{
  "experimental": {
    "vlmSwitchMode": "once"
  }
}

Available modes:

• "once" - Switch to vision model for this query only, then revert
• "session" - Switch to vision model for the entire session
• "persist" - Continue with current model (no switching)
• Not set - Show interactive dialog each time (default)

Command Line Override

You can also set the behavior via command line:

# Switch once per query
frog --vlm-switch-mode once

# Switch for entire session
frog --vlm-switch-mode session

# Never switch automatically
frog --vlm-switch-mode persist

Disable Vision Models (Optional)

To completely disable vision model support, add to your .frog/settings.json:

{
  "experimental": {
    "visionModelPreview": false
  }
}

💡 Tip: In YOLO mode (--yolo), vision switching happens automatically without prompts when images are detected.

Authorization

Choose your preferred authentication method based on your needs:

OpenAI-Compatible API

Use API keys for OpenAI or other compatible providers:

Configuration Methods:

1. Environment Variables

   export OPENAI_API_KEY="your_api_key_here"
   export OPENAI_BASE_URL="your_api_endpoint"
   export OPENAI_MODEL="your_model_choice"

2. Project .env File Create a .env file in your project root:

   OPENAI_API_KEY=your_api_key_here
   OPENAI_BASE_URL=your_api_endpoint
   OPENAI_MODEL=your_model_choice

API Provider Options

⚠️ Regional Notice:

• Mainland China: Use Alibaba Cloud Bailian or ModelScope
• International: Use Alibaba Cloud ModelStudio or OpenRouter

Option 1: Alibaba Cloud Bailian (Apply for API Key)

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

Option 2: ModelScope (Free Tier) (Apply for API Key)

• ✅ 2,000 free API calls per day
• ⚠️ Connect your Aliyun account to avoid authentication errors

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"

Option 1: Alibaba Cloud ModelStudio (Apply for API Key)

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

Option 2: OpenRouter (Free Tier Available) (Apply for API Key)

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen3-coder:free"

Usage Examples

🔍 Explore Codebases

cd your-project/
frog

# Architecture analysis
> Describe the main pieces of this system's architecture
> What are the key dependencies and how do they interact?
> Find all API endpoints and their authentication methods

💻 Code Development

# Refactoring
> Refactor this function to improve readability and performance
> Convert this class to use dependency injection
> Split this large module into smaller, focused components

# Code generation
> Create a REST API endpoint for user management
> Generate unit tests for the authentication module
> Add error handling to all database operations

🔄 Automate Workflows

# Git automation
> Analyze git commits from the last 7 days, grouped by feature
> Create a changelog from recent commits
> Find all TODO comments and create GitHub issues

# File operations
> Convert all images in this directory to PNG format
> Rename all test files to follow the *.test.ts pattern
> Find and remove all console.log statements

🐛 Debugging & Analysis

# Performance analysis
> Identify performance bottlenecks in this React component
> Find all N+1 query problems in the codebase

# Security audit
> Check for potential SQL injection vulnerabilities
> Find all hardcoded credentials or API keys

Popular Tasks

📚 Understand New Codebases

> What are the core business logic components?
> What security mechanisms are in place?
> How does the data flow through the system?
> What are the main design patterns used?
> Generate a dependency graph for this module

🔨 Code Refactoring & Optimization

> What parts of this module can be optimized?
> Help me refactor this class to follow SOLID principles
> Add proper error handling and logging
> Convert callbacks to async/await pattern
> Implement caching for expensive operations

📝 Documentation & Testing

> Generate comprehensive JSDoc comments for all public APIs
> Write unit tests with edge cases for this component
> Create API documentation in OpenAPI format
> Add inline comments explaining complex algorithms
> Generate a README for this module

🚀 Development Acceleration

> Set up a new Express server with authentication
> Create a React component with TypeScript and tests
> Implement a rate limiter middleware
> Add database migrations for new schema
> Configure CI/CD pipeline for this project

Commands & Shortcuts

Session Commands

• /help - Display available commands
• /clear - Clear conversation history
• /compress - Compress history to save tokens
• /stats - Show current session information
• /exit or /quit - Exit FrogCLI

Keyboard Shortcuts

• Ctrl+C - Cancel current operation
• Ctrl+D - Exit (on empty line)
• Up/Down - Navigate command history

Benchmark Results

Benchmark results coming soon.

Development & Contributing

See CONTRIBUTING.md to learn how to contribute to the project.

For detailed authentication setup, see the authentication guide.

Troubleshooting

If you encounter issues, check the troubleshooting guide.

Acknowledgments

This project is based on Qwen Code and Google Gemini CLI. We acknowledge and appreciate the excellent work of both teams.

License

LICENSE

Star History