Migration Guide

Upgrade from older versions to the latest Gemini CLI

Migration Overview

This guide helps you migrate from older versions of Gemini CLI to the latest version. We'll cover breaking changes, configuration updates, and provide step-by-step instructions for a smooth transition.

Current Version
2.0.0
Supported Migrations
This guide covers migration from versions 1.x to 2.0.0

Version Compatibility Matrix

Check which migration path applies to your current version

1.0.x - 1.2.x2.0.0
Major
30-60 minutes
Breaking Changes: High
1.3.x - 1.5.x2.0.0
Moderate
15-30 minutes
Breaking Changes: Medium
1.6.x - 1.9.x2.0.0
Minor
5-15 minutes
Breaking Changes: Low

Breaking Changes in v2.0.0

Important changes that may affect your existing setup

Configuration

Configuration File Format

The configuration file format has changed from JSON to YAML for better readability and comments support.

Impact Level
High
Migration
Use the built-in migration tool: gemini config migrate

Before (v1.x)

{
  "api_key": "your-key",
  "model": "gemini-pro"
}

After (v2.0)

api_key: your-key
model: gemini-pro
# Comments are now supported!
Commands

Command Structure Changes

Some commands have been renamed or restructured for consistency.

Impact Level
Medium
Migration
Update your scripts and aliases

Command Changes

gemini chatgemini ask
gemini generategemini create
gemini config showgemini config list
API

API Key Management

API keys are now stored in a more secure format with encryption.

Impact Level
Low
Migration
Re-run: gemini config set api-key YOUR_KEY

Your existing API key will be automatically migrated on first run

Step-by-Step Migration

Follow these steps to migrate to Gemini CLI v2.0.0

1

Backup Your Configuration

Create a backup of your current configuration before starting the migration.

Commands:

gemini config list > gemini-config-backup.txt
cp ~/.gemini/config.json ~/.gemini/config.json.backup

This ensures you can restore your settings if needed.

2

Update Gemini CLI

Install the latest version of Gemini CLI.

Commands:

npm update -g @google/generative-ai-cli

Verification:

gemini --version
3

Run Migration Tool

Use the built-in migration tool to update your configuration.

Commands:

gemini config migrate

This will automatically convert your configuration to the new format.

4

Verify Configuration

Check that your configuration has been migrated correctly.

Commands:

gemini config list
gemini ask "Hello, testing migration"

Ensure all your settings are preserved and the CLI works as expected.

5

Update Scripts and Aliases

Update any scripts or aliases that use the old command syntax.

Refer to the command changes section above for specific updates needed.

Migration Troubleshooting

Common issues and their solutions

Configuration migration failed

Symptoms:

  • Error: Unable to migrate configuration
  • Config file not found

Solutions:

  1. Ensure you have write permissions to the ~/.gemini directory
  2. Check if the old config file exists: ls ~/.gemini/
  3. Try manual migration: gemini config migrate --force

Commands not working after migration

Symptoms:

  • Command not found errors
  • Unexpected behavior

Solutions:

  1. Clear your shell cache: hash -r
  2. Restart your terminal session
  3. Check the new command syntax in the documentation

API key not working

Symptoms:

  • Authentication errors
  • Invalid API key messages

Solutions:

  1. Re-set your API key: gemini config set api-key YOUR_KEY
  2. Verify the key is correct: gemini config get api-key
  3. Check API key permissions in Google AI Studio

Rollback Instructions

How to revert to the previous version if needed

⚠️ Only use rollback if you encounter critical issues that prevent normal operation.

  1. 1
    Uninstall current version: npm uninstall -g @google/generative-ai-cli
  2. 2
    Install previous version: npm install -g @google/generative-ai-cli@1.9.0
  3. 3
    Restore configuration: cp ~/.gemini/config.json.backup ~/.gemini/config.json
  4. 4
    Verify rollback: gemini --version

Post-Migration Steps

Recommended actions after successful migration

Update Documentation

Medium

Update any internal documentation or team guides to reflect the new command syntax.

Test Automation Scripts

High

Run your automated scripts and CI/CD pipelines to ensure they work with the new version.

Explore New Features

Low

Check out the new features and improvements in v2.0.0.

Learn more

Clean Up Backups

Low

After confirming everything works, you can remove the backup files.

Need Help with Migration?

If you encounter any issues during migration, our community is here to help.

Get SupportView Troubleshooting Guide