grokctl

Drives Grok Imagine through real Chrome — every result proven by bytes on disk, never by the page's word.

$ grokctl gen "a ceramic coffee mug"
fire → real Chrome tab → stream → post/get → bytes
✓ child 016ec262 · media.jpg 77 KB verified on disk

$ grokctl video 016ec262 "steam rising" --length=3 --resolution=480p
✓ media.mp4 393 KB · 3.0 s · ♪ audio (byte-parsed) · verified

$ grokctl edit 016ec262 "…"
✗ reason: moderated — the fire worked, the output was blocked. Terminal, not a retry.

Real Chrome over CDP 10 verbs Full local HTTP API On-page panel 427 tests

Why it exists

Its predecessor — a 27,000-line userscript — judged its own generations from inside the page, and reported green on broken features for weeks. grokctl inverts the trust model: it drives a real logged-in Chrome from the outside over the DevTools protocol, and nothing the page says counts as success. A generation is done when an independent post/get resolves the new post and the media bytes are fetched, size-checked, and archived to disk. A click, an HTTP 200, or a success toast is never proof.

What it does

Ten CLI verbs — generate, edit, multi-reference merge, image→video, extend, upload, download, and native agent-mode operations — plus a token-gated local server exposing the full surface: library search over ~7,000 archived items, folders, remote feeds, quota, templates, a video suite, and a panel injected into grok.com that renders context and fires nothing itself. Four jobs run in parallel, each owning its own browser tab with crash-safe lease reclaim.

Every failure has a name

The part that makes it dependable: no generic errors. Every outcome maps to a reason with a defined operator action —

Reason	Meaning	Operator does
`moderated`	Fire worked; output blocked upstream	Record it. One rewritten retry, max
`stuck-timeout-90000ms`	Wall clock exceeded	Only that job's tab dies — never restart the browser
`source-post-not-found`	Post invisible to this login	Check the account, not the bytes
`disk-write-failed`	Bytes arrived, disk refused	Free space; surviving siblings are kept

Even audio is verified at the byte level: the platform's metadata reports every video as silent, so grokctl parses the mp4 box tree itself to report the truth.

Built to be driven by agents

The repo ships an operator contract (AGENTS.md + project skills) so a coding agent can run the whole thing like a service: a one-command doctor preflight proves the chain end-to-end, then the agent takes plain-language requests — "merge these two", "make it a video" — fires the right verbs, and reports back only what verification proved.