<p align="center" <img src="assets/banner.jpg" alt="grokcli" width="100%" </p
██████╗ ██████╗ ██████╗ ██╗ ██╗ ██████╗ ██╗ ██╗
██╔════╝ ██╔══██╗ ██╔═══██╗ ██║ ██╔╝ ██╔════╝ ██║ ██║
██║ ███╗ ██████╔╝ ██║ ██║ █████╔╝ ██║ ██║ ██║
██║ ██║ ██╔══██╗ ██║ ██║ ██╔═██╗ ██║ ██║ ██║
╚██████╔╝ ██║ ██║ ╚██████╔╝ ██║ ██╗ ╚██████╗ ╚██████╗ ╚█║
╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚╝<p align="center" <bEverything Grok. In your terminal. Zero dependencies.</b<br One login with your SuperGrok or X Premium+ subscription unlocks the full xAI stack —<br chat · web & X search · images · video · voice. No API key. No pip installs. Just Python's stdlib. </p
<p align="center" <a href="README.zh-CN.md"中文</a · <a href="https://docs.x.ai"xAI API docs</a · <a href="#quickstart"Quickstart</a · <a href="#command-reference"Command reference</a </p
<p align="center" <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="python 3.9+" <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="zero dependencies" <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" <img src="https://img.shields.io/badge/tests-375%20passing-8A2BE2" alt="375 tests passing" </p
---
✨ Why you'll love it
| | | |---|---| | 🔑 Your subscription is the key | Browser OAuth (PKCE) with your SuperGrok / X Premium+ account. No API keys, no per-token billing — your subscription just works. | | 📦 Zero dependencies, forever | Pure Python 3.9+ standard library. Runs anywhere Python runs: no nodemodules, no Rust toolchain, no third-party packages. | | 🎛️ Every Grok modality, one command | Chat & reasoning, X + web search with citations, image generation & editing, text/image/reference-to-video, video editing & extension, TTS, speech-to-text, custom voices. | | 🤖 Built for agents | Stable exit codes, --output json, and a fully self-contained manual — grokcli help prints the entire documentation in a single call. | | 🧵 Conversations that continue | Sessions persist locally (bounded), resume across invocations with -c, and never leak to the cloud. |
🤖 Install with your agent (recommended)
grokcli is made for agents — so the fastest way to install it is to let one do it. Copy this prompt into Claude Code (or Cursor, Codex, any coding agent):
Install the "grokcli" command-line tool for me. It is a zero-dependency CLI for xAI's
Grok that authenticates with my SuperGrok / X Premium+ subscription (no API key).
1. Fetch and read https://raw.githubusercontent.com/ele-yufo/grokcli/main/README.md
for full context.
2. Install it (prefer uv; fall back as needed):
uv tool install git+https://github.com/ele-yufo/grokcli
# or: pipx install git+https://github.com/ele-yufo/grokcli
# or: pip install git+https://github.com/ele-yufo/grokcli
3. Verify: run `grokcli --version`, then `grokcli help` (it prints the entire manual
in one call — read it so you know every command).
4. Then walk me through `grokcli login` to connect my account, and run `grokcli doctor`
Once installed, the agent already knows everything: `grokcli help` is the complete,
self-contained manual, and every `grokcli <command> --help` is atomic — prerequisites,
flags, examples, output format, exit codes. No external docs required.
### Manual install
uv tool install git+https://github.com/ele-yufo/grokcli # recommended (isolated, fast) pipx install git+https://github.com/ele-yufo/grokcli # or pipx pip install git+https://github.com/ele-yufo/grokcli # or pip (use a virtualenv)
Then sign in once and verify:
grokcli login # opens your browser; headless? add --manual-paste grokcli doctor # checks auth, connectivity, and entitlement
> Requires Python 3.9+ and an active **SuperGrok** or **X Premium+** subscription.
## 🚀 Quickstart
$ grokcli chat "Explain entropy in one sentence" Entropy measures how many microscopic arrangements match a system's macroscopic state — in short, nature's tendency toward disorder.
$ grokcli image "a red origami fox" -a 16:9 ./grokcli-output/20260806...aredorigamifox.png