Have you ever been in the middle of a long coding session with an AI, only to lose everything because of a network glitch, a dead battery, or an accidental terminal close? It’s frustrating to start over from scratch.

Gemini CLI Tutorial: How to Save and Restore Sessions

Fortunately, the Gemini CLI has a feature called Session Management that solves this exact problem. It allows you to “pick up exactly where you left off,” ensuring your work is never lost.

This guide explains how this feature works, how to use it, and how to configure it to keep your history clean.

Video Tutorial

What is Session Management?

Session management is a built-in feature that automatically saves your interactions with the Gemini CLI. Whether you type one prompt or thirty, Gemini bundles them into a “session.”

Automatic Saving: You don’t need to press a “save” button. The CLI does it in the background after every interaction.
Project Specific: Sessions are tied to the project folder you are working in. If you switch folders, you switch to that folder’s history.
Complete Context: When you restore a session, you get back everything — your prompts, the AI’s answers, and the full context of the conversation.

How to Resume a Session

There are two main ways to restore your work: using the Interactive Mode or the Command Line.

1. The Interactive Method (Easiest)

If you are already inside the Gemini CLI (after typing gemini), you can simply ask to see your history.

Type the command: /resume
A list of your previous sessions will appear.
Select the one you want to continue and hit Enter.

Press enter or click to view image in full size

2. The Command Line Method (Fastest)

You can also restore a session immediately when you launch the tool.

To see all your past sessions: Run this command in your terminal:

gemini --list-sessions

This will show a table with an Index number (e.g., 1, 2, 3) and a Hash (a unique ID code) for each session.

To resume a specific session: Use the --resume flag followed by the index number. For example, to open session #1:

gemini --resume 1

To resume the most recent session: If you just want to go back to exactly where you were last time, simply run:

gemini --resume

Configuring History Settings (Advanced)

By default, Gemini keeps your sessions saved. However, if you use the tool daily, you might end up with too many old sessions clogging up your list.

You can create a Retention Policy to automatically delete old history. This is done by creating a configuration file.

Step 1: Create the Settings File

Navigate to your project folder (or your home directory for global settings) and look for a hidden folder named .gemini. Inside it, create or edit a file named settings.json.

File Path: .gemini/settings.json

Step 2: Add the Retention Rules

Copy and paste the following code into your settings.json file. This fills the gap mentioned in the video by providing the exact code needed:

{  
  "general": {  
    "sessionRetention": {  
      "enabled": true,  
      "maxAge": "30d",  
      "maxCount": 50  
    }  
  }  
}

What do these settings do?

“enabled”: true — Turns on the automatic cleanup feature.
“maxAge”: “30d” — Tells Gemini to delete any session older than 30 days.
“maxCount”: 50 — Tells Gemini to keep only the last 50 sessions.

Summary

The Session Management feature makes the Gemini CLI much more reliable for real work. You no longer have to worry about losing long context windows or complex instructions.

Step-by-Step Guide to Gemini CLI Session Management