Grok CLI 사용법 & 프롬프트 팁

xAI Grok Build 터미널 에이전트 완전 가이드 — 2026-09 기준(grok 1.0.24 stable) · Claude Code 사용자도 바로 적응할 수 있게 구성

⭐ 가장 자주 쓰는 것

Claude Code를 쓰던 사람이라면 이 기능들부터 익히세요. Grok의 진짜 힘은 여기서 나옵니다.

1. Grok Build 개요 · 버전

Grok Build는 xAI의 터미널 기반 코딩 에이전트 제품명이고, 우리가 실제로 치는 명령은 grok 바이너리입니다. 단순 채팅이 아니라 도구 호출(Tools), Plan Mode, 서브에이전트, Skills/Plugins/MCP, Rhai 워크플로를 갖춘 에이전트 런타임입니다.

버전 타임라인

2. 설치 · 인증 · 업데이트

2-1. 설치

# macOS / Linux
curl -fsSL https://x.ai/cli/install.sh | bash
curl -fsSL https://x.ai/cli/install.sh | bash -s 1.0.24   # 특정 버전 고정

# Windows (PowerShell) — GROK_VERSION 환경변수로 버전 지정
irm https://x.ai/cli/install.ps1 | iex

# npm 경로를 선호하면
npm i -g @xai-official/grok

grok --version   # 1.0.24

2-2. 인증 방식

2-3. 업데이트 제어

grok update              # 최신 stable로
grok update --check      # 새 버전 있는지만 확인
grok update --version 1.0.24
grok update --alpha      # 알파 채널
grok update --stable     # 안정 채널로 복귀

자동 업데이트를 끄는 방법은 세 가지 — 상황에 맞게 고릅니다.

• --no-auto-update — 이번 실행만
• GROK_DISABLE_AUTOUPDATER=1 — 환경 단위(컨테이너·CI에 적합)
• [cli] auto_update = false — 설정 파일에 영구 고정

3. 모델 & 추론 강도

grok models        # 사용 가능한 모델 목록

# 2026-09-09 로컬 1.0.24 기준 출력
Default:   grok-4.5
Available: grok-4.6, grok-4.5

전환 방법

커스텀 모델 (사내 게이트웨이 · 타 프로바이더)

~/.grok/config.toml에 [model.<이름>] 블록을 만들면 자체 엔드포인트를 모델처럼 등록할 수 있습니다.

# ~/.grok/config.toml
[model.internal-gw]
base_url    = "https://llm-gateway.example.com/v1"
env_key     = "INTERNAL_LLM_KEY"   # 이 환경변수에서 키를 읽음
api_backend = "chat_completions"    # chat_completions | responses | messages

4. 슬래시 명령어 (/)

프롬프트 맨 앞에 /를 입력하면 자동완성 목록이 나옵니다. 아래는 자주 쓰는 것 위주 정리입니다.

4-1. 세션 관리

4-2. 모드 · 모델 · UI

4-3. 워크플로 & 메모리

# 5분마다 서버 로그 확인 + 이상 있으면 보고
/loop 5m "server.log 마지막 30줄을 보고 에러가 있으면 알려줘"

# 매시간 테스트 실행
/loop 1h "npm test -- --watchAll=false 실행해서 실패 있으면 요약해줘"

# 간격은 최소 60초. /loop 10s 같은 건 받아주지 않는다

4-4. 설정 · 도구 · 계정

5. 핵심 도구 (Tools)

Grok은 프롬프트만으로 대답하는 게 아니라 실제로 도구를 호출해 파일을 읽고 고치고 명령을 실행합니다. 도구 이름을 알아두면 프롬프트를 훨씬 정확하게 쓸 수 있습니다.

파일 · 셸 · 검색 (매일 쓰는 것)

에이전트 · 백그라운드

웹 · 대화 · 확장 · 생성

먼저 @app.py 를 read_file로 확인하고,
넓게 찾아야 하는 부분은 grep으로 위치를 특정한 뒤,
수정은 반드시 search_replace로 정확히 고쳐줘.
단계는 todo_write로 관리하고,
선택이 갈리는 지점은 임의로 정하지 말고 ask_user_question으로 물어봐.

6. 권한 모드 & 규칙

"승인 프롬프트가 뜨느냐 마느냐"를 결정하는 축입니다. always-approve 하나만 있는 게 아닙니다.

권한 규칙 문법

도구별로 패턴을 걸어 허용·질문·거부를 지정합니다. 우선순위는 deny > ask > allow — 거부가 언제나 이깁니다.

Bash(git status)        # 특정 셸 명령
Bash(rm -rf *)          # 보통 deny 목록에 넣는다
Edit(src/**)            # 편집 대상 경로
Read(.env)              # 읽기 차단에 유용
Write(dist/**)
Grep(...)
WebFetch(...)
MCPTool(...)

7. Sandbox (OS 격리) 기본 off

권한 모드가 "물어볼까 말까"라면, 샌드박스는 OS 커널 수준에서 실제로 못 하게 막는 장치입니다. Linux는 Landlock(+bubblewrap), macOS는 Seatbelt를 씁니다. 두 축은 독립이라 조합해서 쓰는 게 정석입니다.

grok --sandbox workspace          # 실행 시 프로필 지정
export GROK_SANDBOX=strict        # 환경변수로 고정

• 세분화가 필요하면 ~/.grok/sandbox.toml에 커스텀 프로필을 정의한다.
• 프로필은 세션에 고정된다 — 다른 --sandbox 값으로 같은 세션을 resume 하려 하면 거부된다.

grok --sandbox strict --always-approve \
     --deny 'Bash(rm -rf *)' \
     -p "이 저장소의 테스트를 돌리고 실패 원인을 요약해줘"

# always-approve로 프롬프트는 없애되,
# 실제 파괴 가능 범위는 샌드박스와 deny 규칙이 물리적으로 제한한다

8. Plan Mode 상세

영향 범위가 큰 작업에서 계획을 먼저 확정시키는 전용 모드입니다. 모델이 스스로 필요성을 판단해 제안하기도 하고, 사용자가 직접 넣을 수도 있습니다.

# 진입하면서 주제까지 함께 지정
/plan 인증 모듈을 세션 기반에서 JWT로 옮기는 계획

# 계획 확인
/view-plan

# 계획 단계에서 조사가 필요하면 편집 권한 없는 타입으로
explore 서브에이전트로 현재 세션 처리 코드가 어디에 흩어져 있는지만 모아줘

9. 서브에이전트 · Agents · Personas

spawn_subagent로 독립 컨텍스트의 자식 에이전트를 띄웁니다. 자식은 자기 컨텍스트에서 일하고 요약만 부모에게 돌려주므로, 메인 세션의 토큰과 집중도를 아낍니다.

9-1. Agents vs Personas — 다른 개념이다

내장 서브에이전트 타입

9-2. spawn_subagent 파라미터

도구 권한은 capability로도 좁힙니다 — read-only · read-write · execute · all.

서브에이전트를 아예 끄려면 GROK_SUBAGENTS=0 또는 --no-subagents를 씁니다.

다음처럼 진행해줘:

1. explore 서브에이전트 2개를 background로 띄워서
   - 하나는 현재 결제 관련 코드 위치를 모으고
   - 하나는 테스트 커버리지 현황을 정리
2. 두 결과가 모이면 todo_write로 단계 정의
3. 실제 구현은 isolation을 worktree로 준 서브에이전트에서 진행
   (메인 작업 트리를 건드리지 않게)
4. 진행 중인 자식에게 방향을 바꿔야 하면 send_subagent_message로 지시

9-3. Worktree 격리

같은 저장소를 여러 작업 트리로 갈라 서로 간섭 없이 병렬 작업할 수 있습니다.

grok -w feat/payments            # --worktree : 새 worktree에서 세션 시작
grok -w feat/payments --ref main # 분기 기준 지정

grok worktree list               # worktree 관리 서브커맨드

• 서브에이전트 쪽은 isolation: "worktree"로 같은 효과를 낸다.
• Dashboard에서는 Ctrl+W로 worktree 관련 화면에 접근한다.
• grok clone(Grove)은 이와 별개의 기능·별개의 인증 게이트다.

10. Skills · Plugins · Hooks · MCP · Workflows

Skills

SKILL.md로 반복 절차를 고정합니다. 탐색 경로는 .grok/skills, .agents/skills이며, Claude·Cursor의 스킬 경로도 호환 스캔합니다 — 기존 자산을 그대로 재사용할 수 있습니다.

# 프로젝트 스킬
.grok/skills/<name>/SKILL.md
# 사용자 전역 스킬
~/.grok/skills/<name>/SKILL.md

Plugins & Marketplace

grok plugin list
grok plugin marketplace add <source>
grok plugin install <name>

Hooks

세션·도구·서브에이전트 생명주기에 셸 명령을 붙입니다.

• SessionStart / SessionEnd
• PreToolUse / PostToolUse
• PermissionDenied — 거부가 발생했을 때
• Stop* · Subagent* · Compact* 계열

훅도 플러그인과 마찬가지로 폴더 신뢰(folder trust)가 공통 게이트입니다. 신뢰하지 않은 폴더의 훅은 돌지 않습니다.

MCP

grok mcp list
grok mcp add <name>
grok mcp remove <name>
grok mcp doctor        # 연결 문제 진단

설정은 [mcp_servers.*]에 두고 stdio · HTTP · SSE 전송을 지원합니다. 세션 안에서는 /mcps로 관리하고, 모델은 search_tool/use_tool로 MCP 도구를 찾아 씁니다.

Workflows (Rhai)

Grok의 차별점 중 하나. Rhai 스크립트로 다단계·병렬 에이전트 절차를 코드로 적어둡니다.

• 위치: .grok/workflows/*.rhai
• 명령: /create-workflow · /workflow · /workflows, 내장 예로 /deep-research
• 에이전트 예산 agent_budget 기본값 128
• 전부 끄려면 GROK_WORKFLOWS=0

11. Headless · ACP · Dashboard

Headless (-p) — CI에 꽂는 방법

grok -p "…" --output-format plain|json|streaming-json|streaming-messages-json

# 권한·격리·거부 규칙을 함께 건다
grok -p "…" --always-approve --sandbox strict --deny 'Bash(rm -rf *)'

# 도구 화이트/블랙리스트와 턴 상한
grok -p "…" --tools "read_file,grep" --disallowed-tools "Agent(explore)" --max-turns 20

# 세션 이어가기
grok -p "…" -r <세션ID>      # resume
grok -p "…" -c               # continue
grok -p "…" --fork-session   # 원본을 건드리지 않고 갈라서 실행

ACP — 에디터에 Grok을 붙이기

# stdio 모드 (에디터가 프로세스를 직접 띄움)
grok agent --always-approve stdio

# 서버 모드
grok agent --always-approve serve --bind 127.0.0.1:2419 --secret <토큰>

• 프로토콜은 JSON-RPC. 권한은 _meta.yoloMode / autoMode로 전달한다.
• 알려진 클라이언트: Zed · Neovim · Emacs · marimo 등.

Dashboard

grok dashboard · 세션 안에서 /dashboard · 단축키 Ctrl+\. 탑레벨 세션 roster를 띄워 여러 작업을 오가며 관리합니다. 앞서 말했듯 서브에이전트는 목록에 없습니다.

12. 세션 저장 & Memory

세션

# 저장 위치
~/.grok/sessions/<인코딩된-작업경로>/<uuid>/

grok sessions          # 목록
grok export <id>       # 내보내기
grok import            # Claude Code 세션 가져오기 (세션 안에서는 /import-claude)
grok usage <id>        # 해당 세션 사용량

Memory — 실험적, 기본 off

세션을 넘어 지속되는 메모리 기능입니다. 기본적으로 꺼져 있고, 켜야 대부분의 명령이 의미를 갖습니다.

# 켜기 — 둘 중 하나
export GROK_MEMORY=1
# 또는 config.toml
[memory]
enabled = true

13. 설정 계층 · 엔터프라이즈 · 네트워크

우선순위

관리형 설정을 내려받는 명령은 grok setup입니다.

네트워크 · 관측

• 프록시: HTTPS_PROXY · HTTP_PROXY · NO_PROXY 를 문서화하고 있다.
  SOCKS 프록시 지원 여부는 명시 확인 필요 — 문서에 HTTPS 계열만 적혀 있다. (참고로 Claude Code는 SOCKS를 공식 미지원으로 못박고 있다)
• OTEL: GROK_EXTERNAL_OTEL 등으로 외부 수집기에 텔레메트리를 보낼 수 있다(alpha 스키마 v1).
• 상태 표시줄: [ui.status_line] — 기본 disabled.

14. 키보드 단축키

15. Claude Code ↔ Grok Build 매핑

Claude Code를 쓰던 사람이 같은 일을 Grok에서 어떻게 하는지 정리했습니다. 이름이 같아도 범위가 다른 항목은 비고에 적어 두었습니다.

16. Grok 프롬프트 작성 팁

1. 도구를 의식해서 말하기

Grok은 도구를 통해 작업합니다. "파일 읽고 수정해"보다 도구를 지정하면 훨씬 정확해집니다.

좋은 예:
먼저 @index.html 의 Program 섹션을 read_file로 확인하고,
새 항목을 추가할 위치를 grep으로 특정한 뒤,
search_replace로 정확히 한 군데만 고쳐줘.

나쁜 예:
Grok 가이드 메뉴 좀 추가해줘.

2. 큰 작업은 /plan부터

/plan 인증 모듈 리팩토링

# 또는 대화로 유도
이건 아키텍처 영향이 커. enter_plan_mode로 먼저 계획을 세우고,
승인 후에 todo_write로 단계를 정의해줘.

3. 병렬화는 명시적으로

조사·구현·검증을 동시에 돌리고 싶다면 몇 개를, 어떤 타입으로, background 여부까지 말해주세요. 편집이 일어나면 안 되는 조사에는 explore를 지정합니다.

4. 정확한 위치 지정

search_replace는 정확한 old_string을 요구합니다. "대략 이 부분"보다 함수명·주변 두세 줄을 함께 알려주는 편이 실패가 적습니다.

5. 위험 작업은 권한이 아니라 격리로 막기

# "조심해서 해줘"는 안전장치가 아니다. 실제로 막는 건 이것들이다.
grok --sandbox workspace --deny 'Bash(rm -rf *)' --deny 'Read(.env)'

6. 애매하면 되묻게 하기

선택지가 갈리는 작업에서는 ask_user_question을 쓰라고 지시하세요. 모델이 임의로 정해버리고 한참 진행한 뒤 되돌리는 비용이 훨씬 큽니다.

17. 체크리스트 & 실전 패턴

새 프로젝트에서 처음 켤 때

1. grok --version으로 버전 확인, 필요하면 grok update
2. grok models로 기본 모델이 무엇인지 직접 확인 (4.5/4.6 문서 불일치 주의)
3. grok doctor · grok inspect --json으로 환경 점검
4. AGENTS.md에 프로젝트 규칙을 적어둔다
5. 위험 명령을 deny 규칙에 넣고, 남의 코드라면 --sandbox workspace부터

큰 작업 루틴

1. /new로 깨끗한 세션
2. /plan <설명> → /view-plan으로 검토 → exit_plan_mode에서 a 승인
3. todo_write로 단계 정의
4. 조사는 explore 자식에게, 구현은 isolation: worktree 자식에게
5. 수정은 search_replace, 진행은 get_command_or_subagent_output으로 확인
6. 끝나면 /compact 또는 /new

CI에 붙일 때

1. XAI_API_KEY 주입 (모델별 api_key가 있으면 그게 먼저 쓰인다는 점 유의)
2. GROK_DISABLE_AUTOUPDATER=1로 실행 중 버전 변동 차단
3. grok -p + --output-format json + --max-turns
4. 권한은 dontAsk(allow 목록) 또는 --always-approve + --sandbox strict
5. --deny로 파괴적 명령을 명시 차단