grok-image-cli

A CLI for generating and editing images using the xAI Grok API. Supports multiple models: grok-imagine-image (default), grok-imagine-image-pro, grok-2-image-1212. Powered by the official @ai-sdk/xai SDK. Credentials are stored in the OS native credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service) via cross-keychain.

Installation

Requires Node.js >= 20.19.0. Works on macOS, Windows, and Linux. The package is fully open source under the MIT license: https://github.com/cyberash-dev/grok-image-cli

npm install -g grok-image-cli

The npm package is published with provenance attestation, linking each release to its source commit via GitHub Actions. You can verify the published contents before installing:

npm pack grok-image-cli --dry-run

Install from source (if you prefer to audit the code before running):

git clone https://github.com/cyberash-dev/grok-image-cli.git
cd grok-image-cli
npm install && npm run build && npm link

After installation the grok-img command is available globally.

Quick Start

grok-img auth login                                                      # Interactive prompt: enter xAI API key
grok-img generate "A futuristic city skyline at night"                   # Generate with default model
grok-img generate "A futuristic city skyline at night" -m grok-imagine-image-pro  # Use pro model
grok-img edit "Make it a watercolor painting" -i ./photo.jpg             # Edit an existing image

API Key Management

Store API key (interactive prompt):

grok-img auth login

Show stored key (masked) and source:

grok-img auth status

Remove key from credential store:

grok-img auth logout

The CLI also supports the XAI_API_KEY environment variable as a fallback when no credential store entry is found.

Image Generation

grok-img generate "A collage of London landmarks in street-art style"
grok-img generate "Mountain landscape at sunrise" -n 4 -a 16:9
grok-img generate "A serene Japanese garden" -o ./my-images
grok-img generate "Photorealistic portrait" -m grok-imagine-image-pro
grok-img generate "Abstract art" -m grok-2-image-1212

Image Editing

Edit a local file or a remote URL:

grok-img edit "Change the landmarks to New York City" -i ./landmarks.jpg
grok-img edit "Render as a pencil sketch" -i https://example.com/portrait.jpg
grok-img edit "Add a vintage film grain effect" -i ./photo.jpg -a 3:2 -o ./edited

Flag Reference

generate

edit

Security and Data Storage

The following properties are by design and can be verified in the source code:

• xAI API key: stored in the OS native credential store via cross-keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service; service: grok-image-cli, account: api-key). By design, never written to disk in plaintext. If no credential store entry is found, the CLI falls back to the XAI_API_KEY environment variable. See src/infrastructure/adapters/credential-store.adapter.ts for the implementation.
• No config files: all settings are passed via CLI flags. Nothing is stored on disk besides the credential store entry.
• Network: the API key is only sent to api.x.ai over HTTPS via the official @ai-sdk/xai SDK. When editing images with a remote URL (-i https://...), the SDK makes an additional outbound HTTPS request to fetch the source image. No other outbound connections are made by the CLI itself (npm/git fetches during installation are standard package manager behavior). See src/infrastructure/adapters/grok-api.adapter.ts.
• Generated images: saved to the local output directory (default: ./grok-images). No images are cached or uploaded elsewhere.

API Reference

This CLI wraps the xAI Image Generation API via the Vercel AI SDK:

• Generation: POST /v1/images/generations
• Editing: POST /v1/images/edits