Gemini CLI 가이드: 체크포인트·복원과 안전한 복구

InYourLeague 리서치 · 2026-08-27

Answer in brief

Gemini CLI 체크포인트는 승인된 파일 변경 도구가 실행되기 전에 로컬 복구 데이터를 저장하도록 사용자가 선택적으로 활성화하는 기능입니다. 복원하면 캡처된 프로젝트 파일과 대화가 해당 시점으로 돌아가며, 기록된 도구 호출은 자동으로 실행되지 않고 다시 제안됩니다.

Key facts at a glance

Failure modes and verification

FAQ

Gemini CLI에서 체크포인트 기능은 기본으로 활성화되나요?

아니요. general.checkpointing.enabled의 기본값은 false입니다. 현재 세션에서는 gemini --checkpointing을 사용하고, 지속적으로 사용하려면 공식 구성 문서에 따라 적용 대상 settings.json에서 활성화합니다.

체크포인트는 정확히 언제 생성되나요?

사용자가 파일 시스템을 변경하는 AI 기반 도구를 승인한 뒤, 해당 도구가 실제 변경을 수행하기 전에 생성됩니다. 공식 문서는 write_file과 replace를 예로 듭니다.

Gemini CLI는 체크포인트 데이터를 어디에 저장하나요?

프로젝트 파일 스냅샷은 ~/.gemini/history/<project_hash>의 섀도 Git 저장소에 보관됩니다. 대화 기록과 도구 호출은 일반적으로 ~/.gemini/tmp/<project_hash>/checkpoints 아래에 JSON 체크포인트 데이터로 저장됩니다.

/restore <checkpoint_file>은 무엇을 복원하나요?

스냅샷에 기록된 프로젝트의 모든 파일과 저장된 대화를 복원합니다. 이후 원래 도구 호출을 다시 제안하며, 사용자는 이를 실행하거나 수정하거나 무시할 수 있습니다.

복원하면 원래 도구 호출이 자동으로 다시 실행되나요?

아니요. 원래 호출은 복원 후 다시 제안될 뿐이며 자동으로 실행되지 않습니다. 다시 제안된 내용을 검토한 뒤 실행 여부를 결정할 수 있습니다.

체크포인트가 Gemini CLI 확장 기능도 백업하나요?

제공된 공식 페이지에는 확장 기능 전용 백업 또는 복원 보장이 없습니다. 확장 기능의 설치 상태, 프로젝트 밖의 설정, 원격 리소스 또는 확장 기능이 관리하는 외부 상태가 캡처된다고도 명시하지 않습니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

핵심 답변

Gemini CLI 체크포인트는 사용자가 선택적으로 활성화하는 복구 기능입니다. 기능이 활성화된 상태에서 사용자가 파일 시스템을 변경할 AI 기반 도구를 승인하면, Gemini CLI는 해당 도구가 실제 변경을 수행하기 전에 체크포인트를 생성합니다. 이후 /restore를 사용하면 캡처된 프로젝트 파일과 대화가 이전 상태로 돌아갑니다. 기록된 도구 호출도 다시 제안되므로 사용자는 이를 실행하거나 수정하거나 무시할 수 있습니다.

체크포인트 기능의 기본값은 비활성화입니다. 현재 세션에서만 사용하려면 Gemini CLI를 gemini --checkpointing으로 시작합니다. 지속적으로 사용하려면 적용할 settings.json에서 general.checkpointing.enabled를 활성화합니다. 자세한 동작과 설정 방식은 공식 체크포인트 문서와 구성 문서에 설명되어 있습니다.

체크포인트에 포함되는 항목

공식 체크포인트 문서가 명시한 구성 요소는 다음 세 가지입니다.

섀도 Git 저장소는 프로젝트 자체의 Git 저장소와 분리되어 있습니다. 따라서 체크포인트 생성 과정에서 프로젝트 저장소에 별도의 커밋이 추가되지는 않습니다. 공식 문서는 체크포인트 데이터가 모두 사용자 컴퓨터에 로컬로 저장된다고 설명합니다. 프로젝트 파일 스냅샷은 홈 디렉터리 아래의 섀도 저장소에 보관되고, 대화와 도구 호출 기록은 프로젝트별 임시 디렉터리에 저장됩니다.

체크포인트 활성화

현재 세션에서 체크포인트를 사용하려면 다음 명령으로 Gemini CLI를 시작합니다.

gemini --checkpointing

여러 세션에서 계속 사용하려면 적용할 settings.json에 다음 설정을 추가합니다.

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

현재 사용자의 모든 Gemini CLI 세션에 적용하려면 ~/.gemini/settings.json을 사용합니다. 특정 프로젝트에만 적용하려면 프로젝트 루트의 .gemini/settings.json을 사용합니다. 설정은 계층별 우선순위에 따라 적용되며, 상위 계층의 값이 하위 계층의 값을 덮어쓸 수 있습니다. 프로젝트 설정은 사용자 설정보다 우선하고, 시스템 재정의 설정, 환경 변수, 명령줄 인수는 두 설정보다 높은 우선순위를 가질 수 있습니다. 설정 파일의 값과 실제 동작이 다르면 상위 우선순위 계층도 확인해야 합니다.

체크포인트 조회와 복원

인수 없이 /restore를 실행하면 현재 프로젝트에 저장된 체크포인트 목록이 표시됩니다. 체크포인트 이름은 일반적으로 생성 시각, 수정 대상 파일 이름, 실행 예정이던 도구 이름을 조합한 형태입니다. 목록에서 정확한 이름을 확인한 뒤 다음과 같이 복원합니다.

/restore <checkpoint_file>

복원 범위는 체크포인트 이름에 표시된 한 파일로 제한되지 않습니다. 스냅샷에 기록된 프로젝트의 모든 파일이 캡처 당시 상태로 돌아가고, 저장된 대화도 함께 복원됩니다. 원래 도구 호출이 다시 나타나지만 /restore만으로 그 호출이 자동 실행되지는 않습니다. 다시 제안된 도구 호출 내용을 검토한 후 실행, 수정, 무시 중에서 선택할 수 있습니다.

승인 경계와 확장 기능

문서에 명시된 체크포인트 생성 경계는 write_file이나 replace처럼 파일 시스템을 변경하는 AI 기반 도구에 대한 사용자의 승인입니다. 제공된 두 공식 페이지는 읽기 전용 도구, 승인되지 않은 제안, 모든 CLI 명령 또는 모든 도구 호출에 체크포인트가 생성된다고 설명하지 않습니다. 따라서 체크포인트를 활성화했다는 사실만으로 모든 작업에 복구 지점이 생긴다고 가정해서는 안 됩니다.

또한 두 페이지에는 확장 기능 전용 체크포인트 또는 복원 정책이 정의되어 있지 않습니다. 확장 기능의 설치 상태, 캡처된 프로젝트 밖의 설정, 원격 리소스 또는 확장 기능이 관리하는 그 밖의 외부 상태가 포함된다고도 명시하지 않습니다. 체크포인트는 문서에 명시된 프로젝트 파일, 대화 기록, 실행 예정인 파일 변경 도구 호출을 위한 복구 수단으로 이해해야 합니다. 확장 기능 전체의 백업으로 간주하지 말고, 중요한 외부 상태는 별도로 보존해야 합니다.

안전한 복원 순서

• 파일 변경 도구를 승인하기 전에 체크포인트가 활성화되어 있었는지 확인합니다.
• /restore로 현재 프로젝트의 목록을 열고 정확한 체크포인트 이름을 확인합니다.
• 복원하면 한 파일이 아니라 캡처된 전체 프로젝트 상태가 영향을 받는다는 점을 고려합니다.
• 복원 후에는 대화와 다시 제안된 도구 호출을 검토한 뒤 다음 변경을 승인합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.