Command Line Interface

Relevant source files

• .gitignore
• README.md
• g4f/Provider/needs_auth/__init__.py
• g4f/__init__.py
• requirements.txt
• setup.py

This page documents the command-line interface (CLI) tools provided by g4f. The CLI offers multiple entry points for running servers, managing authentication, and interacting with providers directly from the terminal.

For information about the HTTP API server, see FastAPI Application. For the web-based graphical interface, see Web GUI. For the Model Context Protocol server integration, see MCP Server Integration.

---

Overview

The g4f package provides several CLI commands installed as console script entry points. These commands enable users to start servers, authenticate with providers, and perform provider-specific operations without writing Python code.

CLI Entry Points:

Command	Module Path	Purpose
g4f	g4f.cli:main	Main CLI interface
g4f-mcp	g4f.mcp.server:main	MCP server for AI assistant integration
g4f-antigravity	g4f.Provider.needs_auth.Antigravity:cli_main	Antigravity provider authentication
g4f-geminicli	g4f.Provider.needs_auth.GeminiCLI:cli_main	Gemini OAuth authentication
g4f-qwencode	g4f.Provider.qwen.QwenCode:cli_main	Qwen Code OAuth authentication
g4f-github-copilot	g4f.Provider.github.GithubCopilot:cli_main	GitHub Copilot authentication

Sources: setup.py118-127

---

CLI Command Structure

Sources: setup.py118-127 README.md189-226

---

Main CLI Entry Point

g4f Command

The g4f command is the primary entry point defined in g4f.cli While the source file is not provided in the context, based on the README usage patterns, it supports subcommands for starting servers.

Common Usage:

Sources: README.md189-205 setup.py120

Python Module Invocation

The CLI can be invoked as a Python module using the -m flag:

Invocation	Functionality
python -m g4f.cli gui	Starts Flask-based web GUI server
python -m g4f	Starts FastAPI/Interference API server
python -m g4f.mcp	Starts MCP server in stdio mode

Sources: README.md189-217

---

GUI Server Command

The GUI server command launches the Flask-based web interface for interactive chat and image generation.

Command Syntax:

Python API Equivalent:

Default Endpoint:

• Web interface: http://localhost:8080/chat/

Common Options:

• --port PORT: Specify server port (default: 8080)
• --debug: Enable debug mode with auto-reload

The GUI server provides:

• Interactive chat interface
• Model and provider selection
• File upload and bucket management
• Image/video/audio generation
• Media display and download

Sources: README.md181-191 README.md500-505

---

FastAPI Server Command

The FastAPI server provides an OpenAI-compatible REST API (Interference API).

Command Syntax:

Docker Slim Configuration:

In slim Docker deployments, the FastAPI server may be mapped to a different port:

Default Endpoints:

• API base: http://localhost:1337/v1 (in slim Docker)
• Swagger UI: http://localhost:1337/docs

The FastAPI server implements OpenAI-compatible endpoints including:

• /v1/chat/completions
• /v1/images/generations
• /v1/models

Sources: README.md193-199 README.md517-523

---

MCP Server Command

The Model Context Protocol (MCP) server exposes g4f capabilities as tools for AI assistants like Claude Desktop.

Starting the MCP Server

Stdio Mode (default):

HTTP Mode:

HTTP Mode Endpoints

Endpoint	Method	Purpose
/mcp	POST	JSON-RPC endpoint for MCP protocol
/health	GET	Health check endpoint

Claude Desktop Configuration

To integrate with Claude Desktop, add the following to claude_desktop_config.json:

Available MCP Tools

The MCP server exposes three tools:

Tool Name	Description
web_search	Search the web using DuckDuckGo
web_scrape	Extract text content from web pages
image_generation	Generate images from text prompts

Sources: README.md208-251 setup.py121

---

Provider-Specific CLI Tools

Several providers expose dedicated CLI commands for authentication and token management.

Command Overview

g4f-geminicli - Gemini OAuth Authentication

Purpose: Authenticates with Google Gemini using OAuth2 PKCE flow.

Entry Point: g4f.Provider.needs_auth.GeminiCLI

Authentication Flow:

1. Starts local callback server on port 51122
2. Opens browser for Google OAuth consent
3. Receives authorization code via callback
4. Exchanges code for access token
5. Caches token in file system

Usage:

The command handles the complete OAuth flow and stores credentials for subsequent requests.

Sources: setup.py123

g4f-antigravity - Antigravity Provider Authentication

Purpose: Authenticates with Antigravity provider using OAuth2 PKCE.

Entry Point: g4f.Provider.needs_auth.Antigravity

Usage:

Similar to GeminiCLI, this implements a PKCE flow with browser-based authentication.

Sources: setup.py122

g4f-qwencode - Qwen Code OAuth

Purpose: Authenticates with Qwen Code using device code flow.

Entry Point: g4f.Provider.qwen.QwenCode

Authentication Flow:

1. Requests device code from provider
2. Displays user authorization URL and code
3. Polls token endpoint until user authorizes
4. Stores access and refresh tokens

Usage:

The device code flow is suitable for CLI environments where opening a browser callback is impractical.

Sources: setup.py124

g4f-github-copilot - GitHub Copilot Token Management

Purpose: Extracts and manages GitHub Copilot authentication tokens.

Entry Point: g4f.Provider.github.GithubCopilot

Usage:

This command may use browser automation (nodriver/zendriver) to extract authentication tokens from an active GitHub Copilot session.

Sources: setup.py125

---

Common Options and Configuration

Environment Variables

The CLI respects environment variables for configuration:

Variable	Purpose	Example
G4F_PROXY	HTTP/SOCKS proxy for provider requests	http://proxy:8080
G4F_VERSION	Package version override	0.3.1.0

Proxy Configuration Example:

The proxy setting is automatically applied to provider requests when the G4F_PROXY environment variable is set.

Sources: g4f/__init__.py49-52 setup.py105

Persistent Storage

CLI commands that involve authentication or media generation use persistent storage directories:

Directory	Purpose
har_and_cookies/	HAR files, cookies, authentication tokens
generated_media/	Images, audio, video outputs
.gui_cache/	Web GUI cached assets

Docker Volume Mapping:

These directories must be writable by the application user (UID 1200:1201 in full Docker, 1000:1000 in slim).

Sources: README.md107-109 README.md128-136

---

CLI Installation and Availability

Installation via pip

CLI commands are automatically installed when installing g4f via pip:

After installation, all console entry points become available in the PATH:

• g4f
• g4f-mcp
• g4f-antigravity
• g4f-geminicli
• g4f-qwencode
• g4f-github-copilot

Partial Installation

For minimal installations without GUI or API dependencies:

Partial installations may exclude some CLI functionality that depends on optional dependencies.

Sources: README.md158-161 setup.py20-96

Windows Executable

Windows users can download a standalone executable that includes CLI functionality:

1. Download g4f.exe.zip from releases
2. Extract and run g4f.exe
3. CLI commands available within the executable environment

Sources: README.md141-150

---

CLI to Code Entity Mapping

Sources: setup.py118-127 README.md183-226

---

Summary

The g4f CLI provides multiple entry points for different use cases:

1. Main CLI (g4f): General-purpose interface for starting servers
2. GUI Server: Flask-based web interface for interactive chat
3. FastAPI Server: OpenAI-compatible REST API
4. MCP Server: Tool exposure for AI assistants
5. Provider CLIs: Dedicated authentication tools for specific providers

All commands support environment variable configuration and persistent storage for authentication data and generated media. The CLI is automatically installed with the g4f package and available in both pip installations and Docker containers.

Sources: setup.py118-127 README.md179-260