A Rust CLI tool for searching X/Twitter, AI image/video generation, and an OpenAI-compatible reverse proxy via xAI API.
- Dual authentication — API Key (
XAI_API_KEY) or OAuth PKCE with automatic token refresh - Search X/Twitter — rich filters: language, date range, engagement, media, verified, ad filtering
- Image generation — text-to-image via Grok Imagine models
- Video generation — text-to-video with async submit+poll, image-to-video, reference images
- OpenAI-compatible proxy — local reverse proxy with automatic OAuth token injection, SSE streaming support
- Structured JSON output —
--jsonflag for scripting and AI tool integration - Musl static builds — cross-compile for x86_64 and arm64 Linux
- Build-time version info (git branch, commit, build timestamp)
One-line install from GitHub Releases (macOS/Linux):
curl -fsSL https://raw.githubusercontent.com/keepmind9/km-xai/main/skills/km-xai/scripts/setup.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/keepmind9/km-xai/main/skills/km-xai/scripts/setup.ps1 | iexOr build from source:
make installInstalls to ~/.local/bin/km-xai.
Two methods, API key takes priority when both are configured:
# Set in ~/.km-xai/.env or environment
export XAI_API_KEY=your-api-keyGet your key at https://console.x.ai
km-xai authOpens the xAI authorization page in your browser. Completes automatically after approval.
If you've already logged in via Grok, credentials are shared automatically — no separate login needed.
# Basic search
km-xai search "Rust programming"
# Filter by user
km-xai search "@elonmusk Mars" --include "elonmusk"
# Exclude users
km-xai search "AI news" --exclude "spambot,promobot"
# Date range (--since/--until are aliases for --from-date/--to-date)
km-xai search "product launch" --since 2025-01-01 --until 2025-06-01
# Enable image/video understanding
km-xai search "landscape photos" --image --video
# Engagement filters
km-xai search "viral post" --min-likes 1000 --min-retweets 500 --no-retweet
# Language and ad filtering
km-xai search "AI" --lang zh-CN --no-ads --verified
# Posts with media
km-xai search "photos" --has-media
# JSON output for scripts
km-xai search "breaking news" --json | jq '.posts[] | {author, text}'
# Custom model and timeout
km-xai search "hello" -m grok-3 --timeout 60| Flag | Description |
|---|---|
-i, --include <handles> |
Filter to these X handles (comma-separated) |
-e, --exclude <handles> |
Exclude these X handles (comma-separated) |
-f, --from-date <YYYY-MM-DD> |
Start date filter (--since alias) |
-t, --to-date <YYYY-MM-DD> |
End date filter (--until alias) |
--image |
Enable image understanding |
--video |
Enable video understanding |
--min-likes <N> |
Minimum likes |
--min-retweets <N> |
Minimum retweets |
--min-replies <N> |
Minimum replies |
--no-retweet |
Exclude retweets (original posts only) |
--verified |
Verified accounts only |
--links |
Posts with links only |
--lang <code> |
Language filter (en, zh-CN, ja, ko, etc.) |
--no-ads |
Exclude promotional/sponsored posts |
--has-media |
Posts with media (images, GIFs, videos) |
--images |
Posts with images only |
--videos |
Posts with videos only |
--replies |
Posts that are replies |
--no-replies |
Exclude replies |
--has-engagement |
Posts with engagement (likes, retweets, replies) |
--json |
Compact JSON output for scripts |
-c, --count <N> |
Limit number of results |
-m, --model <model> |
xAI model (default: grok-4.3) |
--timeout <seconds> |
Request timeout (default: 30) |
# Basic image generation
km-xai image "a sunset over the ocean"
# Save to file
km-xai image "a cute cat" -o cat.jpg
# High quality model with options
km-xai image "cyberpunk city" -m grok-imagine-image-quality --aspect-ratio 16:9 --resolution 2k| Flag | Description |
|---|---|
-m, --model <model> |
Image model (default: grok-imagine-image) |
--aspect-ratio <ratio> |
Aspect ratio (16:9, 1:1, 9:16, 4:3, 3:4, 3:2, 2:3) |
--resolution <res> |
Resolution (1k, 2k) |
-o, --output <path> |
Save to file |
--timeout <seconds> |
Request timeout (default: 120) |
# Basic video generation
km-xai video "a cat jumping off a windowsill"
# Save to file with duration and aspect ratio
km-xai video "ocean waves" --duration 5 --aspect-ratio 16:9 -o waves.mp4
# Image-to-video
km-xai video "zoom into the scene" --image-url https://example.com/scene.jpg
# With reference images
km-xai video "a dance performance" --reference-images "https://img1.jpg,https://img2.jpg"| Flag | Description |
|---|---|
-m, --model <model> |
Video model (default: grok-imagine-video) |
--duration <seconds> |
Duration 1-15 (capped to 10 with reference images) |
--aspect-ratio <ratio> |
Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3) |
--resolution <res> |
Resolution (480p, 720p) |
--image-url <url> |
Input image for image-to-video |
--reference-images <urls> |
Reference images (comma-separated, max 7) |
-o, --output <path> |
Save to file |
--timeout <seconds> |
Polling timeout (default: 240) |
Start a local reverse proxy that injects OAuth tokens and forwards requests to xAI API. Works with any OpenAI-compatible client (Cursor, Continue, etc.).
# Start proxy on default port 9876
km-xai proxy
# Custom port and bind address
km-xai proxy --port 8080 --bind 0.0.0.0Then point your OpenAI-compatible client to http://127.0.0.1:9876:
# Chat completions
curl http://127.0.0.1:9876/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"grok-3-mini","messages":[{"role":"user","content":"hello"}]}'
# Streaming (SSE)
curl http://127.0.0.1:9876/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"grok-3-mini","messages":[{"role":"user","content":"hello"}],"stream":true}'
# Image generation
curl http://127.0.0.1:9876/v1/images/generations \
-H "Content-Type: application/json" \
-d '{"model":"grok-imagine-image","prompt":"a sunset"}'
# Model list
curl http://127.0.0.1:9876/v1/models| Flag | Description |
|---|---|
-p, --port <port> |
Port (default: from PROXY_PORT env, then 9876) |
--bind <addr> |
Bind address (default: from PROXY_BIND env, then 127.0.0.1) |
km-xai status # Show auth status
km-xai version # Show version info
km-xai logout # Clear auth dataConfig directory: ~/.km-xai/ (%APPDATA%/km-xai/ on Windows).
Optional .env file:
XAI_API_KEY=your-api-key
XAI_IMAGE_MODEL=grok-imagine-image
XAI_VIDEO_MODEL=grok-imagine-video
HTTP_PROXY=http://proxy:8080
HTTPS_PROXY=http://proxy:8080
PROXY_PORT=9876
PROXY_BIND=127.0.0.1
make build # Release build
make dev # Debug build
make test # Run unit tests
make check # Type check
make clippy # Lint
make fmt # Format
make release # Musl cross-compile (x86_64 + arm64)OAuth PKCE flow inspired by hermes-agent.
MIT