feat: export session to file and import via flag

packages/cli/src/config/config.test.ts

@@ -234,7 +234,7 @@ describe('parseArguments', () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
-  it('should fail if both --resume and --session-id are provided', async () => {
+  it('should fail if multiple session flags are provided', async () => {
     process.argv = [
       'node',
       'script.js',
@@ -255,7 +255,7 @@ describe('parseArguments', () => {
 
     expect(mockConsoleError).toHaveBeenCalledWith(
       expect.stringContaining(
-        'Cannot use both --resume (-r) and --session-id together',
+        'The flags --resume, --session-id, and --session-file are mutually exclusive. Please provide only one.',
       ),
     );
   });

packages/cli/src/config/config.ts

@@ -97,6 +97,7 @@ export interface CliArgs {
   extensions: string[] | undefined;
   listExtensions: boolean | undefined;
   resume: string | typeof RESUME_LATEST | undefined;
+  sessionFile?: string | undefined;
   sessionId: string | undefined;
   listSessions: boolean | undefined;
   deleteSession: string | undefined;
@@ -239,8 +240,14 @@ export async function parseArguments(
         ? query.length > 0
         : !!query;
 
-      if (argv['resume'] !== undefined && argv['session-id'] !== undefined) {
-        return 'Cannot use both --resume (-r) and --session-id together';
+      const sessionFlags = [
+        argv['resume'] !== undefined,
+        argv['session-id'] !== undefined,
+        argv['session-file'] !== undefined,
+      ].filter(Boolean).length;
+
+      if (sessionFlags > 1) {
+        return 'The flags --resume, --session-id, and --session-file are mutually exclusive. Please provide only one.';
       }
 
       if (argv['prompt'] && hasPositionalQuery) {
@@ -412,6 +419,11 @@ export async function parseArguments(
             return trimmed;
           },
         })
+        .option('session-file', {
+          type: 'string',
+          nargs: 1,
+          description: 'Load a session from a JSON file',
+        })
         .option('session-id', {
           type: 'string',
           nargs: 1,

packages/cli/src/config/mutual-exclusivity.test.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { parseArguments } from './config.js';
+import { createTestMergedSettings } from './settings.js';
+
+describe('parseArguments mutual exclusivity', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const combinations = [
+    ['--resume', '--session-id', 'test-id'],
+    ['--resume', '--session-file', 'test.json'],
+    ['--session-id', 'test-id', '--session-file', 'test.json'],
+    ['--resume', '--session-id', 'test-id', '--session-file', 'test.json'],
+  ];
+
+  combinations.forEach((args) => {
+    it(`should fail if ${args.filter((a) => a.startsWith('--')).join(' and ')} are provided`, async () => {
+      process.argv = ['node', 'script.js', ...args];
+      const mockConsoleError = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      vi.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(parseArguments(createTestMergedSettings())).rejects.toThrow(
+        'process.exit called',
+      );
+
+      expect(mockConsoleError).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'The flags --resume, --session-id, and --session-file are mutually exclusive. Please provide only one.',
+        ),
+      );
+    });
+  });
+});

packages/cli/src/gemini.test.tsx

@@ -44,6 +44,7 @@ import {
   type Config,
   type ResumedSessionData,
   type StartupWarning,
+  type ConversationRecord,
   WarningPriority,
   debugLogger,
   coreEvents,
@@ -828,14 +829,14 @@ describe('gemini.tsx main function kitty protocol', () => {
   });
 
   it('should handle session selector error', async () => {
-    vi.mocked(SessionSelector).mockImplementation(
-      () =>
-        ({
-          resolveSession: vi
-            .fn()
-            .mockRejectedValue(new Error('Session not found')),
-        }) as any, // eslint-disable-line @typescript-eslint/no-explicit-any
-    );
+    // eslint-disable-next-line prefer-arrow-callback
+    vi.mocked(SessionSelector).mockImplementation(function () {
+      return {
+        resolveSession: vi
+          .fn()
+          .mockRejectedValue(new Error('Session not found')),
+      } as unknown as InstanceType<typeof SessionSelector>;
+    });
 
     const processExitSpy = vi
       .spyOn(process, 'exit')
@@ -884,14 +885,14 @@ describe('gemini.tsx main function kitty protocol', () => {
   });
 
   it('should start normally with a warning when no sessions found for resume', async () => {
-    vi.mocked(SessionSelector).mockImplementation(
-      () =>
-        ({
-          resolveSession: vi
-            .fn()
-            .mockRejectedValue(SessionError.noSessionsFound()),
-        }) as unknown as InstanceType<typeof SessionSelector>,
-    );
+    // eslint-disable-next-line prefer-arrow-callback
+    vi.mocked(SessionSelector).mockImplementation(function () {
+      return {
+        resolveSession: vi
+          .fn()
+          .mockRejectedValue(SessionError.noSessionsFound()),
+      } as unknown as InstanceType<typeof SessionSelector>;
+    });
 
     const processExitSpy = vi
       .spyOn(process, 'exit')
@@ -1068,13 +1069,88 @@ describe('resolveSessionId', () => {
     expect(resumedSessionData).toBeUndefined();
   });
 
+  it('should import from session file when sessionFile is provided', async () => {
+    // eslint-disable-next-line prefer-arrow-callback
+    vi.mocked(SessionSelector).mockImplementation(function () {
+      return {
+        sessionExists: vi.fn().mockResolvedValue(false),
+      } as unknown as InstanceType<typeof SessionSelector>;
+    });
+
+    const coreModule = await import('@google/gemini-cli-core');
+    vi.spyOn(coreModule, 'loadConversationRecord').mockResolvedValueOnce({
+      sessionId: 'old-session-id',
+      projectHash: 'hash',
+      startTime: 'time',
+      lastUpdated: 'time',
+      messages: [
+        { type: 'info', content: 'Old info', id: '1' },
+        { type: 'user', content: 'Hello', id: '2' },
+        { type: 'gemini', content: 'Hi', id: '3' },
+        { type: 'error', content: 'Old error', id: '4' },
+        { type: 'user', id: '5' }, // Missing content
+        null, // Null object
+        { type: 'unknown', content: 'Something', id: '6' }, // Unknown type
+      ],
+    } as unknown as ConversationRecord);
+
+    const emitFeedbackSpy = vi.spyOn(coreEvents, 'emitFeedback');
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((code) => {
+        throw new MockProcessExitError(code);
+      });
+
+    try {
+      const { sessionId, resumedSessionData } = await resolveSessionId(
+        undefined,
+        undefined,
+        'dummy-session.json',
+      );
+
+      expect(sessionId).toBeDefined();
+      expect(sessionId).not.toBe('old-session-id'); // A new session ID should be created
+      expect(resumedSessionData).toBeDefined();
+      expect(resumedSessionData?.conversation.sessionId).toBe(sessionId); // Overwritten
+
+      // Verify messages: should have 1 info (the new import confirmation) + 2 valid conversation messages
+      // Invalid messages (missing content, null, unknown type) and transient messages should be filtered out.
+      expect(resumedSessionData?.conversation.messages).toHaveLength(3);
+      expect(resumedSessionData?.conversation.messages![0]).toMatchObject({
+        type: 'info',
+        content: expect.stringContaining('Imported session from'),
+      });
+      expect(resumedSessionData?.conversation.messages![1]).toMatchObject({
+        type: 'user',
+        content: 'Hello',
+      });
+      expect(resumedSessionData?.conversation.messages![2]).toMatchObject({
+        type: 'gemini',
+        content: 'Hi',
+      });
+
+      expect(resumedSessionData?.filePath).toContain(sessionId.slice(0, 8)); // New path
+    } catch (e) {
+      if (e instanceof MockProcessExitError) {
+        throw new Error(
+          'process.exit called with: ' +
+            JSON.stringify(emitFeedbackSpy.mock.calls),
+        );
+      }
+      throw e;
+    } finally {
+      emitFeedbackSpy.mockRestore();
+      processExitSpy.mockRestore();
+    }
+  });
+
   it('should exit with FATAL_INPUT_ERROR when sessionId already exists', async () => {
-    vi.mocked(SessionSelector).mockImplementation(
-      () =>
-        ({
-          sessionExists: vi.fn().mockResolvedValue(true),
-        }) as unknown as InstanceType<typeof SessionSelector>,
-    );
+    // eslint-disable-next-line prefer-arrow-callback
+    vi.mocked(SessionSelector).mockImplementation(function () {
+      return {
+        sessionExists: vi.fn().mockResolvedValue(true),
+      } as unknown as InstanceType<typeof SessionSelector>;
+    });
 
     const emitFeedbackSpy = vi.spyOn(coreEvents, 'emitFeedback');
     const processExitSpy = vi
@@ -1100,12 +1176,12 @@ describe('resolveSessionId', () => {
   });
 
   it('should return provided sessionId when it does not exist', async () => {
-    vi.mocked(SessionSelector).mockImplementation(
-      () =>
-        ({
-          sessionExists: vi.fn().mockResolvedValue(false),
-        }) as unknown as InstanceType<typeof SessionSelector>,
-    );
+    // eslint-disable-next-line prefer-arrow-callback
+    vi.mocked(SessionSelector).mockImplementation(function () {
+      return {
+        sessionExists: vi.fn().mockResolvedValue(false),
+      } as unknown as InstanceType<typeof SessionSelector>;
+    });
     const { sessionId, resumedSessionData } = await resolveSessionId(
       undefined,
       'new-id',

packages/cli/src/gemini.tsx

@@ -35,6 +35,9 @@ import {
   debugLogger,
   isHeadlessMode,
   Storage,
+  getProjectHash,
+  loadConversationRecord,
+  type MessageRecord,
 } from '@google/gemini-cli-core';
 
 import { loadCliConfig, parseArguments } from './config/config.js';
@@ -44,6 +47,8 @@ import { createHash } from 'node:crypto';
 import v8 from 'node:v8';
 import os from 'node:os';
 import dns from 'node:dns';
+import * as path from 'node:path';
+import * as fsPromises from 'node:fs/promises';
 import { start_sandbox } from './utils/sandbox.js';
 import {
   loadSettings,
@@ -194,11 +199,12 @@ ${reason.stack}`
 export async function resolveSessionId(
   resumeArg: string | undefined,
   sessionIdArg?: string | undefined,
+  sessionFileArg?: string | undefined,
 ): Promise<{
   sessionId: string;
   resumedSessionData?: ResumedSessionData;
 }> {
-  if (!resumeArg && !sessionIdArg) {
+  if (!resumeArg && !sessionIdArg && !sessionFileArg) {
     return { sessionId: createSessionId() };
   }
 
@@ -207,6 +213,80 @@ export async function resolveSessionId(
 
   const sessionSelector = new SessionSelector(storage);
 
+  if (sessionFileArg) {
+    try {
+      const sessionData = await loadConversationRecord(sessionFileArg);
+      if (!sessionData) {
+        throw new Error(`File not found or invalid format: ${sessionFileArg}`);
+      }
+
+      const now = Date.now();
+      const isoNow = new Date(now).toISOString();
+
+      // Filter out old system/info messages that are specific to the previous run
+      // and only keep actual conversation messages (user/gemini).
+      // Best effort parse: ensure message is an object and has required fields.
+      sessionData.messages = (sessionData.messages || []).filter(
+        (m) =>
+          typeof m === 'object' &&
+          m !== null &&
+          (m.type === 'user' || m.type === 'gemini') &&
+          m.content !== undefined,
+      );
+
+      // Add a single info message to the history to confirm the import
+      sessionData.messages.unshift({
+        id: `import-${now}`,
+        type: 'info',
+        content: `Imported session from ${sessionFileArg}`,
+        timestamp: isoNow,
+      } as MessageRecord);
+
+      const newSessionId = createSessionId();
+      sessionData.sessionId = newSessionId;
+      sessionData.projectHash = getProjectHash(storage.getProjectRoot());
+      sessionData.startTime = isoNow;
+      sessionData.lastUpdated = isoNow;
+
+      const chatsDir = path.join(storage.getProjectTempDir(), 'chats');
+      const newSessionPath = path.join(
+        chatsDir,
+        `session-${now}-${newSessionId.slice(0, 8)}.jsonl`,
+      );
+
+      const { messages: _messages, ...initialMetadata } = sessionData;
+
+      const lines = [JSON.stringify(initialMetadata)];
+      if (sessionData.messages) {
+        for (const msg of sessionData.messages) {
+          lines.push(JSON.stringify(msg));
+        }
+      }
+
+      await fsPromises.mkdir(chatsDir, { recursive: true });
+      await fsPromises.writeFile(
+        newSessionPath,
+        lines.join('\n') + '\n',
+        'utf-8',
+      );
+
+      return {
+        sessionId: newSessionId,
+        resumedSessionData: {
+          conversation: sessionData,
+          filePath: newSessionPath,
+        },
+      };
+    } catch (error) {
+      coreEvents.emitFeedback(
+        'error',
+        `Error importing session from file: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      await runExitCleanup();
+      process.exit(ExitCodes.FATAL_INPUT_ERROR);
+    }
+  }
+
   if (sessionIdArg) {
     if (await sessionSelector.sessionExists(sessionIdArg)) {
       coreEvents.emitFeedback(
@@ -340,6 +420,7 @@ export async function main() {
   const { sessionId, resumedSessionData } = await resolveSessionId(
     argv.resume,
     argv.sessionId,
+    argv.sessionFile,
   );
 
   if (