Introduction to Gemini CLI#
Google has officially launched Gemini CLI, integrating the powerful capabilities of the Gemini large model directly into the command line interface that developers rely on daily. Not only that, it also offers the largest free usage quota in the industry! By logging in with a personal Google account, you can enjoy up to 60 model requests per minute and 1,000 requests per day, as well as unlock a massive context window of 1 million tokens. Such a generous configuration greatly lowers the development threshold, allowing more people to explore the infinite possibilities of AI-assisted development.
What other incredible "tricks" does Gemini CLI have up its sleeve? How will it reshape our development workflow? Stay tuned, as we will reveal everything next.
Main Features of Gemini CLI#
- Free to use with a personal Google account (up to 60 requests per minute, up to 1,000 requests per day)
- Supports multiple authentication methods
- Customizable color themes
- Supports advanced API key configuration
System Requirements#
Operating System#
- Windows 10 or higher
- macOS 10.15 or higher
- Linux (supports mainstream distributions)
Software Requirements#
- Node.js 18.0.0 or higher
- npm (usually installed with Node.js)
- Stable internet connection
Preparations#
1. Check Node.js Version#
First, open the terminal (Windows users should use PowerShell or Command Prompt) and run the following command to check if Node.js is installed:
node --version
If the displayed version number is lower than 18.0.0 or shows "command not found," you need to install or update Node.js.
2. Install Node.js (if needed)#
For Windows Users:#
- Visit Node.js Official Website
- Download the LTS version (recommended)
- Run the installer and follow the prompts to complete the installation
- Restart the terminal and run
node --version
again to confirm successful installation
For macOS Users:#
Install using Homebrew (recommended):
# If you don't have Homebrew, install it first
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Node.js
brew install node
Or download the installer package from the Node.js official website.
For Linux Users:#
Install using the package manager:
- Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
- CentOS/RHEL/Fedora:
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install nodejs
3. Verify npm Installation#
npm is usually installed with Node.js. Run the following command to confirm:
npm --version
Installation Steps#
Method 1: Run Directly (recommended for first-time use)#
This method does not require global installation and is suitable for quick testing:
npx https://github.com/google-gemini/gemini-cli
Notes:
- The first run will automatically download necessary files
- You may need to wait a few seconds
- Ensure a stable internet connection
Method 2: Global Installation (recommended for frequent use)#
If you plan to use Gemini CLI often, it is recommended to install it globally:
npm install -g @google/gemini-cli
Installation Process Explanation:
- The
-g
flag indicates a global installation - After installation, you can use the
gemini
command in any directory - Administrator privileges may be required (Windows users may need to run the terminal as an administrator)
Resolving Permission Issues#
If you encounter permission errors, try the following methods:
- macOS/Linux:
sudo npm install -g @google/gemini-cli
- Windows: Run PowerShell as an administrator, then execute the installation command.
Configuration and Authentication#
1. First Run#
After installation, run Gemini CLI:
# If using npx
npx https://github.com/google-gemini/gemini-cli
# If installed globally
gemini
2. Choose a Color Theme#
During the first run, the system will prompt you to select a color theme. Use the arrow keys to choose your preferred theme and press Enter to confirm.
3. Google Account Authentication Steps:#
- The CLI will display a URL or automatically open a browser
- Log in to your personal Google account in the browser
- Authorize Gemini CLI to access the necessary permissions
- Copy the displayed authorization code
- Return to the terminal, paste the authorization code, and press Enter
Important Note:
- Using a personal Google account grants you a quota of 60 requests per minute and 1,000 requests per day
- Authentication information will be securely stored locally
- To switch accounts, you can rerun the authentication process
Advanced Configuration#
Using API Key (optional)#
If you need higher request limits or want to use specific models, you can configure an API key:
1. Obtain API Key#
- Visit Google AI Studio
- Log in to your Google account
- Click "Create API Key"
- Copy the generated key (keep it safe and do not share it with others)
2. Set Environment Variable#
- Windows (PowerShell):
$env:GEMINI_API_KEY="YOUR_API_KEY"
- Windows (Command Prompt):
set GEMINI_API_KEY=YOUR_API_KEY
- macOS/Linux:
export GEMINI_API_KEY="YOUR_API_KEY"
3. Permanently Set Environment Variable#
To avoid setting it every time, you can permanently add the environment variable:
- macOS/Linux: Edit
~/.bashrc
,~/.zshrc
, or~/.profile
:
echo 'export GEMINI_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
- Windows:
- Search for "Environment Variables" to open system settings
- Click "New" to add a user variable
- Variable name:
GEMINI_API_KEY
- Variable value: your API key
- Click OK to save and restart the terminal
Other Authentication Methods#
For Google Workspace accounts or other advanced authentication needs, please refer to the official authentication guide.
Common Issues and Solutions#
-
"command not found" Error
- Cause: Node.js or npm is not correctly installed or not added to the system PATH.
- Solution:
- Reinstall Node.js
- Restart the terminal
- Check system PATH settings
-
Network Connection Error
- Cause: Firewall or proxy settings are blocking the connection.
- Solution:
- Check network connection
- Configure proxy (if used):
npm config set proxy http://proxy.example.com:8080 npm config set https-proxy http://proxy.example.com:8080
-
Permission Error
- Cause: Insufficient permissions for global installation.
- Solution:
- Run with administrator privileges
- Or use the npx method to run without global installation
-
API Quota Exceeded
- Cause: Exceeded free quota limits.
- Solution:
- Wait for the quota to reset (resets daily)
- Use API key for higher quota
- Optimize request frequency
Verify Installation#
Basic Functionality Test#
Run the following command to test if Gemini CLI is working properly:
# If installed globally
gemini "Hello, can you introduce yourself?"
# If using npx
npx https://github.com/google-gemini/gemini-cli "Hello, can you introduce yourself?"
Check Version Information#
gemini --version
View Help Information#
gemini --help
Next Steps#
Congratulations! You have successfully installed and configured Gemini CLI. Now you can:
- Explore basic features: Try different prompts and commands
- Check the documentation: Learn more about advanced features and options
- Integrate into your workflow: Incorporate Gemini CLI into your development or creative process
- Customize configuration: Adjust settings and parameters according to your needs