Skip to content

lidge-jun/progrok

BranchesTags

Repository files navigation

progrok

npm version license: MIT docs node

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

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
Reference-to-video --ref <input> repeatable `reference_images: [{url file_id}]`
Edit video progrok video edit ... --video <input> `video: {url file_id}on/v1/videos/edits`
Extend video progrok video extend ... --video <input> `video: {url file_id}on/v1/videos/extensions`
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.

About

Use Grok models for free via OAuth proxy. No API key needed.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages