Grok Image Cli

Generate and edit images via Grok API from the command line. Cross-platform secure credential storage for xAI API key. Supports batch generation, aspect rati...

Security Scan

The skill's requirements and runtime instructions are consistent with a CLI wrapper for xAI image generation and only request the expected API key credential and standard Node tooling.

Purpose & Capability

The name/description (grok-image-cli) align with requested binaries (grok-img, node) and the declared use of an xAI API key; these are reasonable for a CLI that wraps the xAI Grok Image API.

Instruction Scope

SKILL.md instructs the agent to use the grok-img CLI, manage credentials via the OS keychain, call api.x.ai over HTTPS, and optionally fetch remote images when editing — all within the stated image-generation/editing scope. There are no instructions to read unrelated system files or exfiltrate data to other endpoints.

Install Mechanism

No automated install spec is bundled with the skill (instruction-only), but the README provides standard install commands (npm install -g or git clone then npm build). These use known channels (npm, GitHub); user guidance to audit before installing is included. This is normal but the registry lacks an automated install spec.

Credentials

The CLI legitimately needs an xAI API key stored in the OS credential store and optionally accepts XAI_API_KEY as a fallback. There is a small metadata inconsistency: the registry summary showed 'no primary credential' while SKILL.md declares a cross-keychain credential and optional XAI_API_KEY — functionally this is proportional but the metadata mismatch should be corrected.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide configs. It stores only its own API key in the OS credential store (expected behavior for a CLI).

Assessment

This skill appears to do what it says: it's a CLI wrapper around xAI image APIs and requires Node and the grok-img binary plus an xAI API key stored in your OS credential store (or via XAI_API_KEY). Before installing: 1) verify the npm package and GitHub repo (check the provenance/commit referenced) and prefer auditing source if you have concerns; 2) confirm you trust the grok-img binary's origin (npm scope and publisher); 3) be aware that when you use the edit command with a remote image URL the CLI will fetch that URL over HTTPS; 4) note the minor metadata mismatch (registry claims no primary credential but SKILL.md uses a cross-keychain credential) — this is likely an editorial issue but you may want the publisher to correct it. If any of these checks fail, avoid installing or run installation in an isolated environment.

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

Flag	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 to generate (1-10)	1
-o, --output <dir>	Output directory	./grok-images

edit

Flag	Description	Default
-i, --image <path>	Source image (local file 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

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

Documentation: https://docs.x.ai/docs/guides/image-generation