grok-img

CLI for generating and editing images with Grok API, powered by @ai-sdk/xai.

Supports multiple models: grok-imagine-image (default), grok-imagine-image-pro, grok-2-image-1212.

Installation

npm install -g grok-image-cli

From source

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

Authentication

The CLI stores your xAI API key securely in the OS native credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service) via cross-keychain. Alternatively, set the XAI_API_KEY environment variable.

grok-img auth login    # Save API key (interactive prompt)
grok-img auth status   # Check authentication status
grok-img auth logout   # Remove API key

Image Generation

grok-img generate "A futuristic city skyline at night"
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

Options

| Option | Description | Default | |--------|-------------|---------| | -m, --model <model> | Model (grok-imagine-image, grok-imagine-image-pro, grok-2-image-1212) | grok-imagine-image | | -a, --aspect-ratio <ratio> | Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto) | auto | | -n, --count <number> | Number of images (1-10) | 1 | | -o, --output <dir> | Output directory | ./grok-images |

Image Editing

grok-img edit "Make it look like a watercolor painting" -i ./photo.jpg
grok-img edit "Change the sky to sunset colors" -i https://example.com/photo.jpg
grok-img edit "Add a vintage film grain effect" -i ./photo.jpg -a 3:2 -o ./edited
grok-img edit "Render as pencil sketch" -i ./photo.jpg -m grok-imagine-image-pro

Options

| Option | Description | Default | |--------|-------------|---------| | -i, --image <path> | Source image (local path or URL) | required | | -m, --model <model> | Model (grok-imagine-image, grok-imagine-image-pro, grok-2-image-1212) | grok-imagine-image | | -a, --aspect-ratio <ratio> | Aspect ratio | auto | | -o, --output <dir> | Output directory | ./grok-images |

Models

| Model | Modalities | Rate Limit | Price | |-------|------------|------------|-------| | grok-imagine-image | text, image -> image | 300 RPM | $0.02/image | | grok-imagine-image-pro | text, image -> image | 30 RPM | $0.07/image | | grok-2-image-1212 | text -> image | 300 RPM | $0.07/image |

grok-2-image-1212 does not support aspect_ratio: "auto" or image editing.

Development

npm install
npm run dev          # watch mode
npm run build        # production build
npm run lint         # check linting
npm run lint:fix     # auto-fix lint issues
npm run format       # format code

Architecture

This project follows Clean Architecture principles:

src/
  main.ts                        # Composition root
  domain/                        # Entities & port interfaces (zero deps)
  application/                   # Use cases (depends on domain only)
  infrastructure/                # Adapters (@ai-sdk/xai, cross-keychain, fs)
  presentation/                  # CLI commands (commander)

Requirements

• Node.js >= 20.19.0
• macOS, Windows, or Linux
• xAI API key from console.x.ai

License

MIT