progrok

Activate your xAI Grok OAuth session as a local API and tool surface.

progrok is an OAuth bridge for Grok. It signs in with your xAI account, stores a refreshable local OAuth session, and activates that session through two developer-facing surfaces:

1. an OpenAI-compatible localhost proxy that forwards /v1/* requests to api.x.ai, and
2. direct CLI commands for Grok workflows that need source selection, JSON output, async polling, local files, or machine-readable metadata.

The point is not only "no API key." The point is that Hermes Agent, OpenClaw, and Grok Build-style coding workflows all rely on the same xAI OAuth credential lineage: the xAI account session is the authority, and local tools need a way to turn that session into a programmable endpoint. progrok is that activation tool. Point the OpenAI SDK, curl scripts, or agent tools at 127.0.0.1:18645 and let progrok inject the real xAI bearer token locally.

Requires an active SuperGrok subscription. progrok does not bypass xAI account access, quotas, pricing, or product limits.

Links

• Live docs: lidge-jun.github.io/progrok
• OAuth bridge: lidge-jun.github.io/progrok/docs/concepts/oauth-bridge
• Quick start: lidge-jun.github.io/progrok/docs/quickstart
• npm: npmjs.com/package/progrok
• Repository: github.com/lidge-jun/progrok

Why OAuth

xAI account access is session-based in the tools that made this workflow useful. Hermes Agent and OpenClaw document the shared xAI OAuth client identifier used by progrok, and Grok Build-style coding workflows benefit from the same model: authenticate once with the xAI account, then expose Grok to developer tooling through a local API surface.

That changes the shape of the problem:

• the user account and subscription decide what models and tools are available;
• the local machine holds the refreshable credential;
• existing SDKs and agents expect a base URL plus an API key;
• Grok media, search, and model discovery need more workflow glue than a raw HTTP proxy provides.

progrok handles that glue. It activates the OAuth credential as a proxy for OpenAI-compatible clients and as direct commands for search, images, video, models, and capability discovery.

What "activation tool" means

After progrok login, the stored OAuth session powers every surface below:

| Surface | Command or URL | What gets activated | | --- | --- | --- | | OpenAI-compatible API | http://127.0.0.1:18645/v1/* | Chat, Responses, reasoning, structured output, server-side tools, files, batches, and other HTTP xAI API paths your account can access. | | Current search | progrok search | Grok Responses with web search, X search, citations, JSON output, and optional reasoning effort. | | Image workflows | progrok image | Imagine generation and editing with local reference files and output handling. | | Video workflows | progrok video | Async video submission, polling, progress display, and download handling. | | Coding models | grok-build-0.1 through the proxy | Grok Build-style coding work from clients that can point at a local OpenAI-compatible endpoint. | | Agent discovery | progrok capabilities --json | Machine-readable ports, commands, models, endpoints, and auth requirements. |

The placeholder OPENAI_API_KEY or Authorization value is only there to satisfy client libraries. progrok replaces it before forwarding the request.

Install

npm install -g progrok

Quick Start

# 1. Activate your xAI OAuth session.
progrok login

# SSH or remote machine:
progrok login --device-code

# 2. Start the OpenAI-compatible local proxy.
progrok proxy

# 3. Call Grok through localhost.
curl http://127.0.0.1:18645/v1/chat/completions \
  -H "Authorization: Bearer anything" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4.3","messages":[{"role":"user","content":"Hello"}]}'

The proxy replaces the placeholder Authorization value with your stored xAI OAuth bearer token before forwarding the request. The API key value in your client can be any non-empty placeholder.

For direct tool activation, the proxy process is optional:

progrok search --x --json "Grok Build release discussion"
progrok image "a precise product diagram of an OAuth bridge CLI" --output ./out
progrok video "a local proxy turning on Grok tools" --duration 5
progrok models --detail
progrok capabilities --json

OpenAI SDK Example

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18645/v1",
    api_key="anything",
)

result = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "Explain MCP in 5 bullets"}],
)

print(result.choices[0].message.content)

Shell configuration for tools that respect OpenAI-compatible environment variables:

export OPENAI_BASE_URL=http://127.0.0.1:18645/v1
export OPENAI_API_KEY=anything

Commands

| Command | Use it for | | --- | --- | | progrok login | Browser OAuth login with your xAI account. | | progrok login --device-code | OAuth login for SSH, CI shells, or remote machines. | | progrok logout | Remove stored local credentials. | | progrok status | Check whether a local OAuth session exists. | | progrok proxy | Start the local OpenAI-compatible proxy on 127.0.0.1:18645. | | progrok chat | Open the local browser chat UI on 127.0.0.1:18646. | | progrok models --detail | List model aliases, pricing, context windows, and media models. | | progrok search <query> | Search web and X sources through Grok Responses tools. | | progrok search <query> --web | Restrict search to web sources. | | progrok search <query> --x | Restrict search to X sources. | | progrok search <query> --reasoning high | Add reasoning effort to a search request. | | progrok image <prompt> | Generate an Imagine image. | | progrok image <prompt> --ref ./input.png | Edit or compose from a reference image. | | progrok video <prompt> | Text-to-video generation. | | progrok video <prompt> --image ./input.png | Image-to-video (animate still image). | | progrok video edit <prompt> --video <url> | Edit existing video with text (real V2V). grok-imagine-video only. | | progrok video extend <prompt> --video <url> | Continue video from last frame. grok-imagine-video only. | | progrok capabilities --json | Print machine-readable command, model, and endpoint metadata. | | progrok skill | Print an agent-oriented usage guide. |

Native Search

progrok search calls xAI's Responses API directly with web_search and x_search tools. It does not require the proxy process to be running because it loads the same OAuth session directly.

progrok search "latest Astro release"
progrok search --web "Node.js 22 features"
progrok search --x "grok API launch"
progrok search --json "rust async traits"
progrok search --model grok-4.20-multi-agent-0309 --reasoning xhigh \
  "compare current open-source browser automation tools"

Reasoning effort values: none, low, medium, high, xhigh.

Image and Video

Image generation:

progrok image "a crisp terminal UI product shot for a CLI called progrok"
progrok image "make this diagram cleaner" --ref ./diagram.png --output ./out

Video generation:

# Text-to-video
progrok video "a terminal command expanding into a network diagram"

# Image-to-video (animate a still image)
progrok video "turn this interface into a smooth product demo" --image ./screen.png

# Reference-to-video (guide the scene with up to 7 images, max 10s)
progrok video "put this character in a quiet terminal workspace" \
  --ref ./character.png --ref ./workspace.png --duration 6

# Video editing — modify existing video, keep motion (grok-imagine-video only)
progrok video edit "Make the background a sunset sky" --video ./clip.mp4

# Video extension — continue from last frame (grok-imagine-video only)
progrok video extend "Camera slowly pulls back revealing the full scene" \
  --video file_id:file-abc123 --duration 5

Model constraints

| Model | T2V | I2V | Ref2V | Edit | Extend | |-------|:---:|:---:|:-----:|:----:|:------:| | grok-imagine-video | ✅ | ✅ | ✅ | ✅ | ✅ | | grok-imagine-video-1.5-preview | ❌¹ | ✅ | ❌¹ | ❌ | ❌ |

¹ xAI's model page describes text+image input, but live OAuth smoke returned Text-to-video is not supported for this model for prompt-only T2V and ``reference_images is not supported for this model for Ref2V. progrok treats 1.5-preview as I2V-only until the API changes.

Video API surface map

| Surface | CLI | REST canonical shape | Status | | --- | --- | --- | --- | | Text-to-video | progrok video "<prompt>" | prompt only on /v1/videos/generations | Supported | | Image-to-video | --image <file|url|data|file_id:id> | image: {url | file_id} | Supported | | Reference-to-video | --ref <input> repeatable | reference_images: [{url | file_id}] | Supported, max 7 refs, max 10s | | Edit video | progrok video edit ... --video <input> | video: {url | file_id} on /v1/videos/edits | Supported on base model | | Extend video | progrok video extend ... --video <input> | video: {url | file_id} on /v1/videos/extensions | Supported on base model | | Duration alias | --seconds <s> | seconds instead of duration | OpenAI-compat alias | | Signed output target | --upload-url <url> | output: {upload_url} | Exposed for signed PUT destinations |

mode: "edit-video" / "extend-video" / "reference-to-video" is a Vercel AI SDK provider option, not a direct REST selector. Live REST smoke accepted a stray mode field but treated the request as ordinary T2V.

Live smoke verdicts

| Probe | Result | | --- | --- | | T2V, I2V, R2V on grok-imagine-video | Passed, status: done | | Edit/extend by source URL | Passed, status: done | | file_id image/video input | Passed for I2V, R2V, edit, and extend | | seconds alias | Passed | | image_url REST alias | Passed | | output.upload_url | Passed with a public PUT endpoint; result video.url equals the upload URL | | video_url REST alias | Failed with 422 missing field video; use video: {url} | | 1080p | Failed for this team: 1080p video resolution is not available for your team | | grok-imagine-video-1.5-preview | I2V passed; prompt-only T2V and Ref2V failed |

Video editing/extension constraints

• Input: .mp4 (H.264/H.265/AV1), max 8.7s (edit) or 2–15s (extend)
• --image, --ref, --video: local file, HTTPS URL, data URI, or file_id:<id>
• Mutual exclusion: --image and --ref cannot be combined; xAI returns 400 Bad Request
• Edit output: Same duration/aspect/resolution as input (max 720p)
• Extend duration: 2–10s (default 6s), added to original
• Model: grok-imagine-video only — 1.5-preview returns "not supported"
• Unsupported knobs: edit ignores/rejects duration/aspect/resolution; extend ignores/rejects aspect/resolution; 1080p appears in one REST schema but current model/docs/pricing pages only confirm 480p/720p

Media commands call xAI endpoints directly with your OAuth session and poll async jobs until completion.

Proxy Coverage

The proxy forwards every HTTP /v1/* path to api.x.ai, so it can activate the xAI API surface available to your account:

• Chat Completions and Responses
• reasoning, citations, structured output, and tool calls
• image generation and editing
• video generation, editing, extension, and polling
• text-to-speech, speech-to-text, and realtime client-secret minting
• files, batches, tokenizer, models, and collection search

WebSocket endpoints are not proxied. For realtime voice streams, mint a client secret through the HTTP proxy and connect directly to xAI's WebSocket endpoint.

Models

| Model | Best for | Context | Notes | | --- | --- | --- | --- | | grok-4.3 | Default chat, tools, search, vision | 1M | Also available through common Grok aliases. | | grok-build-0.1 | Fast agentic coding | 256K | Good default for Grok Build-style coding tools through the OAuth proxy. | | grok-4.20-0309-reasoning | Deep reasoning | 200K+ | Legacy reasoning model. | | grok-4.20-0309-non-reasoning | Lower-latency text | 200K+ | Legacy non-reasoning model. | | grok-4.20-multi-agent-0309 | Deep research | 200K+ | Supports high and xhigh effort. | | grok-imagine-image | Image generation and editing | - | $0.002/input image; $0.02/output image. | | grok-imagine-image-quality | Higher-quality image output | - | $0.01/input image; $0.05 (1K) or $0.07 (2K) output image. | | grok-imagine-video | Video: T2V, I2V, Ref2V, Edit, Extend | - | $0.002/input image, $0.01/input video sec; $0.05/sec (480p), $0.07/sec (720p). | | grok-imagine-video-1.5-preview | Video: I2V only in live smoke; no native T2V/Ref2V/Edit/Extend | - | $0.01/input image; $0.08/sec (480p), $0.14/sec (720p). |

Run the live metadata command before relying on a model in automation:

progrok models --detail
progrok capabilities --json

How It Works

OpenAI client, coding agent, curl script, or local tool
  -> http://127.0.0.1:18645/v1/*
  -> progrok loads ~/.progrok/auth.json
  -> progrok refreshes the token if needed
  -> progrok injects the xAI OAuth bearer token
  -> https://api.x.ai/v1/*

Credentials are stored locally at ~/.progrok/auth.json and refreshed before expiry. Treat that file like any other account credential.

The direct command path is similar but skips the proxy server:

progrok search / image / video / models / capabilities
  -> load the same local OAuth session
  -> call the relevant xAI endpoint
  -> add CLI-specific behavior such as polling, files, or JSON output

Relationship to Hermes Agent, OpenClaw, and Grok Build

progrok's OAuth client attribution comes from Hermes Agent and OpenClaw under their MIT licenses. Those projects demonstrated the important part: Grok can be made useful to local developer tools through xAI OAuth rather than through a manually provisioned API key.

progrok takes that pattern and packages it as a focused bridge:

• Hermes Agent and OpenClaw establish the shared OAuth client lineage.
• Grok Build-style workflows need a coding model reachable from agent tools.
• progrok provides the localhost OpenAI-compatible endpoint and direct commands that let those tools use the same authenticated account session.

This is why the documentation describes progrok as an activation tool. Login is the authorization step; the proxy and CLI commands are the activated surfaces.

Security Notes

• The proxy binds to localhost by default.
• Do not expose the proxy port to a public network without adding your own access controls.
• The placeholder API key sent by OpenAI-compatible clients is ignored by the proxy and replaced with your xAI OAuth token.
• progrok logout removes the local credential file.
• Requests are forwarded to xAI. Sensitive prompt data should be handled under the same policy you use for direct xAI API usage.
• The OAuth file enables account-backed access. Do not commit it, sync it to untrusted machines, or share it between users.

Troubleshooting

progrok status says no session

Run progrok login again. On remote machines, use progrok login --device-code.

The proxy starts but clients fail

Check that the client points to:

http://127.0.0.1:18645/v1

Also check that the client sends a non-empty API key placeholder.

Port 18645 is already in use

Stop the existing process or start the proxy on another port if your version supports a port flag. Then update OPENAI_BASE_URL accordingly.

A model returns 404 or 400

Run:

progrok models --detail

Model aliases and preview names can change. Use the live list before scripting a long-running workflow.

Search, image, or video commands fail

These commands call xAI directly with OAuth and may be subject to product access, rate limits, quota, and account capability. Start with:

progrok status
progrok capabilities --json

License

MIT. See THIRD_PARTY_NOTICES.md for OAuth client attribution.