🪽 Arcplume — Grok Build CLI Session
Use this skill when the user explicitly wants Grok via the locally authenticated Grok Build CLI session and CLI-driven execution.
When to trigger
Trigger on prompts like:
- "use grok build to generate an image"
- "generate an image with grok"
- "run the grok CLI"
- "use my logged-in grok session"
Do not auto-trigger for generic “use Grok API” requests unless the user asks for the CLI/logged-in-session mode.
Default behavior
- Validate local prerequisites (
grok available)
- Verify the session is logged in (
scripts/preflight.sh)
- Execute via CLI-driven headless image generation path
- Keep outputs concise and never expose secrets
Auth resolution order (strict)
- Check the
grok binary is present on PATH
- Check that a logged-in session exists (Grok Build CLI manages its own OAuth tokens; this skill does not resolve or read any env vars or cookie files)
If either check fails, stop and return a precise remediation message.
Mandatory preflight (must pass)
command -v grok && grok --version
bash scripts/preflight.sh
If preflight fails, do not attempt Grok execution. Explain exactly which layer failed:
- binary missing
- session not logged in
- session invalid/expired
Execution path
Primary: CLI-driven headless image generation (recommended)
Drive the already-authenticated grok binary directly:
- Run
scripts/generate-image.sh --prompt "<text>" --out "<path>" (optional --max-turns)
- This invokes
grok headlessly (single-turn, JSON output) with a system-prompt override that forces use of Grok's real built-in image-generation tool, not a hand-drawn approximation
- The script locates the resulting image file and copies it to the requested
--out path
- Return the resolved output path + a brief summary
This path is default because it relies on the CLI's own maintained OAuth session rather than any credential this skill would otherwise have to manage.
Optional: API mode (explicit opt-in only)
If and only if user asks for API mode, or asks for video (Grok Build's own OAuth
session does not expose a native video-generation tool — confirmed by live testing:
asking it to generate video with no workarounds allowed returns an explicit "no
built-in video-generation tool available here" answer):
- Use
XAI_API_KEY
- Call
api.x.ai
- For video: run
scripts/generate-video.sh --prompt "<text>" --out "<path.mp4>"
(optional --duration, --model, --timeout); it wraps the same
api.x.ai/v1/videos/generations endpoint scripts/doctor.sh and
scripts/test-video.sh already exercise, in this skill's standard
--prompt/--out interface
- Clearly mark output as API mode, not CLI-session mode
Hard constraints
- Never print or log the contents of
~/.grok/auth.json, or any API keys
- Never dump the raw JSON response from a headless
grok call — only the resolved output path should ever be printed
- Never persist secrets to files
- Never silently switch from CLI-session mode to API mode
- Never rewrite user prompt without user permission
- For state-changing actions, show draft and request confirmation first
Fast diagnostics snippets
command -v grok >/dev/null 2>&1 && echo "grok: found ($(grok --version))" || echo "grok: missing"
bash scripts/doctor-cli.sh
Failure messaging template
Use this style:
- Failed at: session validation
- Reason:
scripts/preflight.sh reported the Grok Build CLI session is not logged in
- Fix: run
grok login --oauth (interactive) or grok login --device-auth (headless/remote), then retry
Security posture
- Principle of least exposure: only test what is required
- Output redaction by default
- Deterministic preflight before runtime actions
- No destructive action without explicit confirmation
