superagent-ai/grok-cli 설치 및 사용방법
AI 코딩 도구가 점점 많아지고 있습니다. 웹에서 사용하는 챗봇, IDE 확장 도구, 자동화 에이전트까지 선택지가 넓습니다. 그중 grok-cli는 조금 결이 다릅니다. 이 프로젝트는 Grok을 터미널에서 직접 사용할 수 있게 해주는 오픈소스 AI 에이전트입니다. 저장소 소개 문구도 “Grok의 힘을 터미널로 가져오는 오픈소스 AI 에이전트”라고 설명하고 있습니다.
이 글에서는 superagent-ai/grok-cli가 무엇인지, 어떤 기능을 제공하는지, 그리고 실제로 어떻게 설치하고 사용하는지 알아보겠습니다.
grok-cli란 무엇인가?
grok-cli는 터미널 기반 AI 에이전트 도구입니다. 단순히 질문만 주고받는 CLI가 아니라, 코드 작업과 검색, 세션 유지, 서브에이전트, Telegram 원격 제어, 이미지·영상 생성까지 포함하는 비교적 큰 범위의 도구입니다. README에서는 이 프로젝트가 Bun과 OpenTUI 기반으로 만들어졌고, 실시간 X 검색과 웹 검색, 여러 Grok 모델, 서브에이전트, Telegram 원격 제어 기능을 제공합니다. 또한 이 프로젝트는 커뮤니티가 만든 비공식 도구이며, xAI의 공식 Grok CLI는 아니라고 명시하고 있습니다.
즉, 한 줄로 정리하면 다음과 같습니다.
grok-cli는 Grok API를 활용해 터미널에서 코딩 작업과 검색, 자동화 작업을 수행할 수 있게 해주는 비공식 오픈소스 CLI 에이전트입니다.
주요 특징
grok-cli의 핵심 기능은 다음과 같습니다.
1. Grok 모델 기반 터미널 에이전트
기본적으로 Grok 계열 모델을 사용하도록 설계되어 있습니다. README에는 grok-code-fast-1, grok-4-1-fast-reasoning, grok-4.20-multi-agent-0309 등 다양한 모델 계열이 언급되어 있으며, grok models 명령으로 사용 가능한 모델 목록과 가격 힌트를 확인할 수 있습니다.
2. X 검색과 웹 검색 지원
search_x, search_web 도구를 통해 실시간 정보 검색을 지원합니다. 그래서 단순한 정적 모델 응답이 아니라 최신 포스트나 문서를 참고하는 워크플로우에 적합합니다.
3. 서브에이전트 기본 지원
이 프로젝트는 서브에이전트가 기본 동작으로 포함되어 있습니다. README에서는 포그라운드 작업 위임과 읽기 전용 딥다이브용 백그라운드 delegate를 설명하고 있으며, 필요하면 ~/.grok/user-settings.json에 subAgents를 정의해 사용자 지정 에이전트도 만들 수 있다고 소개합니다.
4. Telegram 원격 제어
TUI에서 /remote-control 메뉴를 통해 Telegram 봇을 연결하면, CLI를 실행해 둔 상태에서 휴대폰으로 에이전트를 제어할 수 있습니다. 추가로 음성 메시지나 오디오 파일을 보내면, 로컬에서 whisper.cpp로 음성을 텍스트로 변환해 처리하는 기능도 제공합니다.
5. 이미지와 영상 생성
일반 채팅 세션 안에서 generate_image, generate_video 도구를 통해 텍스트 기반 이미지 생성, 이미지 편집, 텍스트 기반 영상 생성, 이미지 기반 영상 생성까지 지원한다. 생성된 파일은 기본적으로 .grok/generated-media/ 아래에 저장됩니다.
6. 세션 유지와 헤드리스 모드
이 도구는 대화를 세션으로 저장하고, –session latest 같은 옵션으로 이어서 작업할 수 있습니다. 또한 –prompt 또는 -p를 이용하면 비대화형 실행, 즉 스크립트나 자동화 파이프라인에 적합한 헤드리스 모드로도 사용할 수 있습니다. –format json 옵션을 주면 JSON 이벤트 스트림 형태로 결과를 받을 수 있습니다.
설치 방법
설치는 비교적 단순하다. 저장소 README 기준 설치 명령은 다음과 같다. 패키지 이름은 grok-dev이지만 실제 실행 명령은 grok 입니다.
npm i -g grok-dev
설치 전 준비 사항
README에서 안내하는 사전 조건은 다음과 같습니다.
- Node.js 18 이상
- xAI에서 발급받은 Grok API 키
- 인터랙티브 OpenTUI를 제대로 사용하려면 최신 터미널 에뮬레이터
문서에서 추천하는 터미널은 다음과 같습니다.
- WezTerm
- Alacritty
- Ghostty
- Kitty
인터랙티브 TUI를 쓰지 않고 헤드리스 모드만 사용할 경우에는 터미널 UI 지원이 꼭 필요하지는 않습니다.
API 키 설정 방법
README에서는 여러 방식의 API 키 설정을 지원한다고 안내합니다. 가장 일반적인 방법은 환경변수 설정입니다.
1. 환경변수로 설정
export GROK_API_KEY=your_key_here
2. 프로젝트 .env 파일에 설정
GROK_API_KEY=your_key_here
3. CLI에서 한 번만 입력
grok -k your_key_here
4. 사용자 설정 파일에 저장
~/.grok/user-settings.json 파일에 다음처럼 저장할 수도 있습니다.
{
"apiKey": "your_key_here"
}
추가로 선택적으로 GROK_BASE_URL, GROK_MODEL, GROK_MAX_TOKENS 같은 항목도 설정할 수 있습니다.
기본 사용 방법
1. 인터랙티브 모드 실행
가장 기본적인 사용 방법은 아래 명령이다. 이 명령을 실행하면 OpenTUI 기반의 인터랙티브 에이전트가 실행됩니다.
grok
2. 특정 프로젝트 디렉터리에서 실행
특정 프로젝트를 분석하거나 작업하려면 -d 옵션으로 디렉터리를 지정할 수 있습니다.
grok -d /path/to/your/repo
이 방식은 특정 코드베이스를 기준으로 리팩터링, 테스트 분석, 파일 탐색 같은 작업을 할 때 유용합니다.
3. 헤드리스 모드 실행
스크립트나 CI에서 한 번만 실행하고 종료하려면 --prompt 또는 -p를 사용하면 된다. README 예시는 다음과 같습니다.
grok --prompt "run the test suite and summarize failures"
grok -p "show me package.json" --directory /path/to/project
grok --prompt "refactor X" --max-tool-rounds 30
grok --prompt "summarize the repo state" --format json
이 모드는 자동화 파이프라인이나 로그 수집 용도로도 잘 맞습니다.
4. 저장된 세션 이어서 사용
이전에 작업하던 세션을 다시 열고 싶다면 다음 명령을 사용할 수 있습니다.
grok --session latest
grok -s <session-id>
세션 유지 기능이 있기 때문에, 긴 작업을 여러 번 나누어 이어갈 수 있다는 점도 장점입니다.
5. 모델 목록 확인
사용 가능한 Grok 모델과 가격 힌트를 확인하려면 다음 명령을 사용합니다.
grok models
6. 바로 프롬프트를 넘겨 실행
간단한 작업은 아래처럼 명령 자체에 바로 프롬프트를 붙여 사용할 수도 있습니다.
grok fix the flaky test in src/foo.test.ts
이미지와 영상 생성
grok-cli는 단순 텍스트 작업만 하는 도구가 아니다. 일반 채팅 세션 안에서 이미지나 짧은 영상 생성도 가능합니다. README 예시는 아래와 같습니다.
grok "Generate a retro-futuristic logo for my CLI called Grok Forge"
grok "Edit ./assets/hero.png into a watercolor poster"
grok "Animate ./assets/cover.jpg into a 6 second cinematic push-in"
생성 결과는 기본적으로 .grok/generated-media/ 아래에 저장되며, xAI의 URL이 만료된 이후에도 로컬 파일을 재사용할 수 있게 되어 있습니다.
Telegram 원격 제어 설정
README의 간단 안내를 기준으로 보면 Telegram 원격 제어 설정 흐름은 다음과 같습니다.
- @BotFather에서 봇 생성
- 발급된 봇 토큰 확보
- TELEGRAM_BOT_TOKEN 환경변수 또는 ~/.grok/user-settings.json에 telegram.botToken 설정
- grok 실행 후 /remote-control → Telegram 메뉴 진입
- Telegram에서 봇에게 /pair 전송
- 터미널에 표시된 6자리 코드를 입력해 승인
이 기능을 사용하면 CLI를 켜둔 상태에서 휴대폰으로 명령을 보내 작업을 이어갈 수 있습니다.
음성 메시지 처리 기능
Telegram 연동 시 음성 메시지나 오디오 파일을 텍스트로 변환해 사용하는 기능도 제공합니다. 이때 음성 인식은 클라우드 서비스가 아니라 로컬의 whisper.cpp를 통해 처리됩니다. README 기준 macOS 설치 예시는 다음과 같습니다.
brew install whisper-cpp
brew install ffmpeg
설치 후 아래 명령으로 확인할 수 있습니다.
whisper-cli -h
ffmpeg -version
Whisper 모델은 첫 사용 시 자동 다운로드되거나, 직접 내려받아 경로를 지정할 수 있다. 예시 설정은 다음과 같습니다.
{
"telegram": {
"botToken": "YOUR_BOT_TOKEN",
"audioInput": {
"enabled": true,
"binaryPath": "/opt/homebrew/bin/whisper-cli",
"model": "tiny.en",
"modelPath": "~/.grok/models/stt/whisper.cpp/ggml-tiny.en.bin",
"autoDownloadModel": true,
"language": "en"
}
}
}
개발 환경에서 직접 빌드하기
패키지를 글로벌 설치해서 쓰는 방식 외에, 저장소를 직접 클론해서 개발 모드로 실행할 수도 있다. README의 개발 명령은 다음과 같습니다.
bun install
bun run build
bun run start
추가로 다음 명령도 제공합니다.
bun run dev
bun run typecheck
bun run lint
즉, 이 프로젝트는 단순 사용뿐 아니라 포크해서 직접 수정하고 확장하는 용도도 고려하고 있습니다.
장점
grok-cli의 장점은 명확합니다.
첫째, 터미널 중심 워크플로우에 잘 맞는다. IDE를 벗어나 쉘 환경에서 바로 에이전트를 사용할 수 있다는 점이 매력적입니다.
둘째, 검색과 에이전트 기능이 결합되어 있다. 실시간 X 검색, 웹 검색, 서브에이전트, 세션 유지가 함께 제공되기 때문에 단순 질의응답형 CLI보다 활용 범위가 넓습니다.
셋째, Telegram 원격 제어와 미디어 생성 같은 확장 기능이 있습니다. 단순 코드 보조 도구를 넘어 자동화와 원격 운용까지 염두에 둔 구조입니다.
넷째, 오픈소스 프로젝트라 직접 수정하고 확장하기 쉽습니다. 저장소는 MIT 라이선스를 사용하며 TypeScript 기반으로 작성되어 있습니다.
아쉬운 점
반면 주의할 점도 있습니다.
이 프로젝트는 README에서 직접 밝히듯 xAI 공식 도구가 아닙니다. 따라서 장기 안정성이나 공식 지원을 기대하기보다는, 커뮤니티 주도 프로젝트라는 점을 감안하고 접근하는 것이 좋습니다.
또한 기능이 매우 많은 편이어서, 실제 운영 환경에 바로 연결하기보다는 먼저 로컬 테스트나 샌드박스 프로젝트에서 검증하는 편이 안전합니다. 특히 Telegram 연동, 세션 지속, MCP 확장 같은 기능은 편리하지만 권한 관리에도 신경 써야 합니다.
마무리
superagent-ai/grok-cli는 단순한 “Grok용 명령줄 래퍼” 수준을 넘어서, 터미널 기반 AI 에이전트 플랫폼에 가까운 프로젝트입니다. Grok 모델 기반 코딩 에이전트, 실시간 검색, 서브에이전트, Telegram 원격 제어, 이미지·영상 생성까지 묶여 있어 실험용으로는 꽤 매력적입니다. 다만 공식 제품이 아닌 만큼, 운영 환경보다는 개인 개발 환경이나 테스트 프로젝트에서 먼저 검증하며 사용하는 것이 적절할 것 같습니다.
Grok을 터미널에서 적극적으로 활용해 보고 싶다면, grok-cli는 한 번쯤 설치해서 살펴볼 만한 리포지토리입니다.