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
CODEBLOCK0
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:
CODEBLOCK1
Install from source (if you prefer to audit the code before running):
CODEBLOCK2
After installation the grok-img command is available globally.
Quick Start
CODEBLOCK3
API Key Management
Store API key (interactive prompt):
CODEBLOCK4
Show stored key (masked) and source:
CODEBLOCK5
Remove key from credential store:
CODEBLOCK6
The CLI also supports the XAI_API_KEY environment variable as a fallback when no credential store entry is found.
Image Generation
CODEBLOCK7
Image Editing
Edit a local file or a remote URL:
CODEBLOCK8
Flag Reference
generate
| Flag | Description | Default |
|---|
| INLINECODE8 | Model (grok-imagine-image, grok-imagine-image-pro, grok-2-image-1212) | grok-imagine-image |
| INLINECODE9 |
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 |
|---|
| INLINECODE13 | Source image (local file path or URL) | required |
| INLINECODE14 |
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: INLINECODE27
- Editing: INLINECODE28
Documentation: https://docs.x.ai/docs/guides/image-generation
grok-image-cli
一个使用 xAI Grok API 生成和编辑图片的命令行工具。支持多种模型：grok-imagine-image（默认）、grok-imagine-image-pro、grok-2-image-1212。由官方 @ai-sdk/xai SDK 驱动。凭据通过 cross-keychain 存储在操作系统原生凭据存储中（macOS 钥匙串、Windows 凭据管理器、Linux 密钥服务）。
安装
需要 Node.js >= 20.19.0。支持 macOS、Windows 和 Linux。该软件包完全开源，采用 MIT 许可证：https://github.com/cyberash-dev/grok-image-cli
bash
npm install -g grok-image-cli
npm 软件包附带来源证明，通过 GitHub Actions 将每个版本链接到其源代码提交。您可以在安装前验证发布的内容：
bash
npm pack grok-image-cli --dry-run
从源代码安装（如果您希望在运行前审核代码）：
bash
git clone https://github.com/cyberash-dev/grok-image-cli.git
cd grok-image-cli
npm install && npm run build && npm link
安装后，grok-img 命令可在全局使用。
快速开始
bash
grok-img auth login # 交互式提示：输入 xAI API 密钥
grok-img generate 未来主义城市天际线夜景 # 使用默认模型生成
grok-img generate 未来主义城市天际线夜景 -m grok-imagine-image-pro # 使用专业模型
grok-img edit 将其改为水彩画风格 -i ./photo.jpg # 编辑现有图片
API 密钥管理
存储 API 密钥（交互式提示）：
bash
grok-img auth login
显示已存储的密钥（掩码显示）及来源：
bash
grok-img auth status
从凭据存储中移除密钥：
bash
grok-img auth logout
当凭据存储中未找到条目时，该 CLI 也支持使用 XAIAPIKEY 环境变量作为后备方案。
图片生成
bash
grok-img generate 街头艺术风格的伦敦地标拼贴画
grok-img generate 日出时的山景 -n 4 -a 16:9
grok-img generate 宁静的日本花园 -o ./my-images
grok-img generate 逼真肖像照 -m grok-imagine-image-pro
grok-img generate 抽象艺术 -m grok-2-image-1212
图片编辑
编辑本地文件或远程 URL：
bash
grok-img edit 将地标改为纽约市 -i ./landmarks.jpg
grok-img edit 渲染为铅笔素描 -i https://example.com/portrait.jpg
grok-img edit 添加复古胶片颗粒效果 -i ./photo.jpg -a 3:2 -o ./edited
参数参考
generate
| 参数 | 描述 | 默认值 |
|---|
| -m, --model <model> | 模型（grok-imagine-image、grok-imagine-image-pro、grok-2-image-1212） | grok-imagine-image |
| -a, --aspect-ratio <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
| 生成图片数量（1-10） | 1 |
| -o, --output | 输出目录 | ./grok-images |
edit
| 参数 | 描述 | 默认值 |
|---|
| -i, --image <path> | 源图片（本地文件路径或 URL） | 必填 |
| -m, --model <model> |
模型（grok-imagine-image、grok-imagine-image-pro、grok-2-image-1212） | grok-imagine-image |
| -a, --aspect-ratio | 宽高比 | auto |
| -o, --output | 输出目录 | ./grok-images |
安全与数据存储
以下属性是设计使然，可在源代码中验证：
- - xAI API 密钥：通过 cross-keychain 存储在操作系统原生凭据存储中（macOS 钥匙串 / Windows 凭据管理器 / Linux 密钥服务；服务名：grok-image-cli，账户名：api-key）。设计上，永远不会以明文形式写入磁盘。如果未找到凭据存储条目，CLI 将回退到 XAIAPIKEY 环境变量。实现详见 src/infrastructure/adapters/credential-store.adapter.ts。
- 无配置文件：所有设置均通过 CLI 参数传递。除凭据存储条目外，不会在磁盘上存储任何内容。
- 网络：API 密钥仅通过官方 @ai-sdk/xai SDK 经 HTTPS 发送至 api.x.ai。当使用远程 URL（-i https://...）编辑图片时，SDK 会额外发起一个出站 HTTPS 请求以获取源图片。CLI 本身不会发起其他出站连接（安装期间的 npm/git 拉取属于标准包管理器行为）。详见 src/infrastructure/adapters/grok-api.adapter.ts。
- 生成的图片：保存到本地输出目录（默认：./grok-images）。不会在其他地方缓存或上传图片。
API 参考
此 CLI 通过 Vercel AI SDK 封装了 xAI 图片生成 API：
- - 生成：POST /v1/images/generations
- 编辑：POST /v1/images/edits
文档：https://docs.x.ai/docs/guides/image-generation
