Docs
Gemini CLI 사용하기
셸 명령

셸 도구 (run_shell_command)

이 문서는 Gemini CLI의 run_shell_command 도구에 대해 설명합니다.

설명

run_shell_command를 사용하여 기본 시스템과 상호 작용하고, 스크립트를 실행하거나, 명령줄 작업을 수행합니다. run_shell_command는 tools.shell.enableInteractiveShell 설정이 true로 설정된 경우 사용자 입력이 필요한 대화형 명령(예: vim, git rebase -i)을 포함하여 주어진 셸 명령을 실행합니다.

Windows에서는 ComSpec이 다른 셸을 가리키도록 명시적으로 지정하지 않는 한 powershell.exe -NoProfile -Command로 명령이 실행됩니다. 다른 플랫폼에서는 bash -c로 실행됩니다.

인수

run_shell_command는 다음 인수를 받습니다:

  • command (string, 필수): 실행할 정확한 셸 명령입니다.
  • description (string, 선택): 사용자에게 표시될 명령의 목적에 대한 간략한 설명입니다.
  • directory (string, 선택): 명령을 실행할 디렉토리(프로젝트 루트 기준)입니다. 제공되지 않으면 명령은 프로젝트 루트에서 실행됩니다.

Gemini CLI에서 run_shell_command를 사용하는 방법

run_shell_command를 사용할 때 명령은 하위 프로세스로 실행됩니다. run_shell_command는 &를 사용하여 백그라운드 프로세스를 시작할 수 있습니다. 이 도구는 다음을 포함하여 실행에 대한 자세한 정보를 반환합니다:

  • Command: 실행된 명령입니다.
  • Directory: 명령이 실행된 디렉토리입니다.
  • Stdout: 표준 출력 스트림의 출력입니다.
  • Stderr: 표준 오류 스트림의 출력입니다.
  • Error: 하위 프로세스에서 보고된 모든 오류 메시지입니다.
  • Exit Code: 명령의 종료 코드입니다.
  • Signal: 명령이 신호에 의해 종료된 경우 신호 번호입니다.
  • Background PIDs: 시작된 백그라운드 프로세스의 PID 목록입니다.

사용법:

run_shell_command(command="여기에 명령 입력.", description="명령에 대한 설명.", directory="실행 디렉토리.")

run_shell_command 예제

현재 디렉토리의 파일 나열:

run_shell_command(command="ls -la")

특정 디렉토리에서 스크립트 실행:

run_shell_command(command="./my_script.sh", directory="scripts", description="내 사용자 정의 스크립트 실행")

백그라운드 서버 시작:

run_shell_command(command="npm run dev &", description="백그라운드에서 개발 서버 시작")

구성

settings.json 파일을 수정하거나 Gemini CLI의 /settings 명령을 사용하여 run_shell_command 도구의 동작을 구성할 수 있습니다.

대화형 명령 활성화

대화형 명령을 활성화하려면 tools.shell.enableInteractiveShell 설정을 true로 설정해야 합니다. 이렇게 되면 셸 명령 실행에 node-pty를 사용하여 대화형 세션을 허용합니다. node-pty를 사용할 수 없는 경우 대화형 명령을 지원하지 않는 child_process 구현으로 대체됩니다.

settings.json 예시:

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true
    }
  }
}

출력에 색상 표시

셸 출력에 색상을 표시하려면 tools.shell.showColor 설정을 true로 설정해야 합니다. 참고: 이 설정은 tools.shell.enableInteractiveShell이 활성화된 경우에만 적용됩니다.

settings.json 예시:

{
  "tools": {
    "shell": {
      "showColor": true
    }
  }
}

호출기 설정

tools.shell.pager를 설정하여 셸 출력에 대한 사용자 정의 호출기를 지정할 수 있습니다. 기본 호출기는 cat입니다. 참고: 이 설정은 tools.shell.enableInteractiveShell이 활성화된 경우에만 적용됩니다.

settings.json 예시:

{
  "tools": {
    "shell": {
      "pager": "less"
    }
  }
}

대화형 명령

run_shell_command 도구는 이제 사이비 터미널(pty)을 통합하여 대화형 명령을 지원합니다. 이를 통해 텍스트 편집기(vim, nano), 터미널 기반 UI(htop), 대화형 버전 제어 작업 (git rebase -i)과 같이 실시간 사용자 입력이 필요한 명령을 실행할 수 있습니다.

대화형 명령이 실행 중일 때 Gemini CLI에서 입력을 보낼 수 있습니다. 대화형 셸에 포커스를 맞추려면 Tab을 누르세요. 복잡한 TUI를 포함한 터미널 출력이 올바르게 렌더링됩니다.

중요 참고 사항

  • 보안: 명령을 실행할 때, 특히 사용자 입력으로 구성된 명령을 실행할 때 보안 취약점을 방지하기 위해 주의하세요.
  • 오류 처리: Stderr, Error 및 Exit Code 필드를 확인하여 명령이 성공적으로 실행되었는지 확인하세요.
  • 백그라운드 프로세스: &를 사용하여 백그라운드에서 명령을 실행하면 도구가 즉시 반환되고 프로세스는 백그라운드에서 계속 실행됩니다. Background PIDs 필드에는 백그라운드 프로세스의 프로세스 ID가 포함됩니다.

환경 변수

run_shell_command가 명령을 실행할 때 하위 프로세스의 환경에 GEMINI_CLI=1 환경 변수를 설정합니다. 이를 통해 스크립트나 도구가 Gemini CLI 내에서 실행되고 있음을 감지할 수 있습니다.

명령 제한

구성 파일의 tools.core 및 tools.exclude 설정을 사용하여 run_shell_command 도구로 실행할 수 있는 명령을 제한할 수 있습니다.

  • tools.core: run_shell_command를 특정 명령 집합으로 제한하려면 tools 카테고리 아래의 core 목록에 run_shell_command(<command>) 형식을 사용하여 항목을 추가하세요. 예를 들어, "tools": {"core": ["run_shell_command(git)"]}는 git 명령만 허용합니다. 일반적인 run_shell_command를 포함하면 와일드카드로 작동하여 명시적으로 차단되지 않은 모든 명령을 허용합니다.
  • tools.exclude: 특정 명령을 차단하려면 tools 카테고리 아래의 exclude 목록에 run_shell_command(<command>) 형식을 사용하여 항목을 추가하세요. 예를 들어, "tools": {"exclude": ["run_shell_command(rm)"]}는 rm 명령을 차단합니다.

유효성 검사 로직은 안전하고 유연하게 설계되었습니다:

  1. 명령 체이닝 비활성화: 도구는 &&, || 또는 ;로 연결된 명령을 자동으로 분할하고 각 부분을 개별적으로 검증합니다. 체인의 일부가 허용되지 않으면 전체 명령이 차단됩니다.
  2. 접두사 일치: 도구는 접두사 일치를 사용합니다. 예를 들어 git을 허용하면 git status 또는 git log를 실행할 수 있습니다.
  3. 차단 목록 우선순위: tools.exclude 목록이 항상 먼저 확인됩니다. 명령이 차단된 접두사와 일치하면 tools.core에서 허용된 접두사와 일치하더라도 거부됩니다.

명령 제한 예제

특정 명령 접두사만 허용

git 및 npm 명령만 허용하고 다른 모든 명령을 차단하려면:

{
  "tools": {
    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
  }
}
  • git status: 허용됨
  • npm install: 허용됨
  • ls -l: 차단됨

특정 명령 접두사 차단

rm을 차단하고 다른 모든 명령을 허용하려면:

{
  "tools": {
    "core": ["run_shell_command"],
    "exclude": ["run_shell_command(rm)"]
  }
}
  • rm -rf /: 차단됨
  • git status: 허용됨
  • npm install: 허용됨

차단 목록 우선순위

명령 접두사가 tools.core 및 tools.exclude 모두에 있으면 차단됩니다.

{
  "tools": {
    "core": ["run_shell_command(git)"],
    "exclude": ["run_shell_command(git push)"]
  }
}
  • git push origin main: 차단됨
  • git status: 허용됨

모든 셸 명령 차단

모든 셸 명령을 차단하려면 tools.exclude에 run_shell_command 와일드카드를 추가하세요:

{
  "tools": {
    "exclude": ["run_shell_command"]
  }
}
  • ls -l: 차단됨
  • any other command: 차단됨

excludeTools에 대한 보안 참고 사항

run_shell_command에 대한 excludeTools의 명령별 제한은 간단한 문자열 일치를 기반으로 하며 쉽게 우회될 수 있습니다. 이 기능은 보안 메커니즘이 아니며 신뢰할 수 없는 코드를 안전하게 실행하기 위해 의존해서는 안 됩니다. coreTools를 사용하여 실행할 수 있는 명령을 명시적으로 선택하는 것이 좋습니다.

파일 관리메모리 관리