grokly

A minimal CLI wrapper around the xAI Responses API for single-turn prompts, multi-turn chat, streaming output, and local job files for manual polling.

Table of Contents

• Background
• Install
• Usage
• Agent Examples (Claude Code, Codex)
• Configuration
• Tools
• Tests
• Contributing
• License

Background

xAI’s preferred interface is the Responses API. It supports stateful conversations via previous_response_id and streaming output, but it does not expose server-side polling for in-progress requests. grokly wraps the Responses API directly and provides a local job file workflow so an agent can check progress and read results later without using deprecated endpoints.

Install

Run via npx (recommended):

npx @bytes032/grokly --help

Or install globally:

npm install -g @bytes032/grokly
grokly --help

Usage

Single‑turn:

npx @bytes032/grokly respond -m grok-4-1-fast -p "Summarize this project."

Multi‑turn with a session file:

npx @bytes032/grokly chat -m grok-4-1-fast --session .grokly-session -p "Start a new thread."
npx @bytes032/grokly chat -m grok-4-1-fast --session .grokly-session -p "Follow up with more detail."

Allowlisted web/X search:

npx @bytes032/grokly respond -m grok-4-1-fast \
  --tools web,x \
  --allow docs.noble.xyz,@noble_xyz \
  -p "Find latest updates."

Streaming:

npx @bytes032/grokly respond -m grok-4-1-fast --stream -p "Write a long answer."

Local job file (manual polling):

npx @bytes032/grokly respond -m grok-4-1-fast -p "Deep research" --slug run1
npx @bytes032/grokly status
npx @bytes032/grokly job status ./jobs/run1.json
npx @bytes032/grokly job result ./jobs/run1.json --render
npx @bytes032/grokly render ./jobs/run1.json.result.json

Clean up old jobs:

npx @bytes032/grokly status --clean --hours 24

Example agent/LLM workflows (X search)

Pull recent updates from specific X accounts with citations:

npx @bytes032/grokly respond -m grok-4-1-fast \
  --tools x \
  --allow @noble_xyz,@cosmos \
  --include-citations \
  --output ./x-notes.json \
  -p "Summarize recent updates and cite each claim."

npx @bytes032/grokly render ./x-notes.json

Track a topic across several handles and keep state in a session:

npx @bytes032/grokly chat -m grok-4-1-fast --session .grokly-session \
  --tools x --allow @a16z,@paradigm,@electriccapital \
  -p "Scan for new posts about infra funding; summarize."
npx @bytes032/grokly chat -m grok-4-1-fast --session .grokly-session \
  -p "Update the summary with anything new since last time."

Search X with media understanding (video only works with x_search):

npx @bytes032/grokly respond -m grok-4-1-fast \
  --tools x \
  --allow @openai \
  --capabilities video \
  -p "Summarize the latest demo clip."

Long X research with a job file (manual polling):

npx @bytes032/grokly respond -m grok-4-1-fast \
  --tools x --allow @noble_xyz,@cosmos \
  --slug x-research \
  -p "Deep research on announcements and partnerships."
npx @bytes032/grokly job status ./jobs/x-research.json
npx @bytes032/grokly job result ./jobs/x-research.json --render

Agent Examples (Claude Code, Codex)

These agents do not ship with xAI tools by default. Use the grokly skill (included in this repo) so the agent can invoke the CLI consistently.

Claude Code (shell tool)

Prompt to the agent:

Use the grokly skill to query xAI. Summarize the latest updates for pump.fun and include citations.

What the skill runs (example, via npx):

npx @bytes032/grokly respond -m grok-4-1-fast-reasoning \
  --tools web --allow pump.fun \
  --slug pumpfun-update \
  -p "Summarize the latest updates and include citations."
npx @bytes032/grokly render ./jobs/pumpfun-update.json.result.json

Example response (rendered):

- <Update> (source: https://pump.fun/...)
- <Update> (source: https://pump.fun/...)

Codex (shell tool)

Prompt to the agent:

Use the grokly skill to scan X for new posts about pump.fun from @pumpdotfun. Summarize and keep state.

What the skill runs (example, via npx):

npx @bytes032/grokly chat -m grok-4-1-fast-reasoning \
  --session .grokly-session \
  --tools x --allow @pumpdotfun \
  -p "Scan for new posts about pump.fun; summarize."
npx @bytes032/grokly chat -m grok-4-1-fast-reasoning \
  --session .grokly-session \
  -p "Update the summary with anything new since last time."

Example response (rendered):

- @pumpdotfun posted <update> on <date>.
- <Summary of additional post>.

Commands

grokly respond

Single‑turn Responses API request.

Options:

• -m, --model <id> (required)
• -p, --prompt <text> (or stdin)
• --system <text>
• --messages <path> JSON array of {role, content} (overrides prompt/system)
• --tools <list>: web,x,code
• --allow <list>: domains and @handles
• --capabilities <list>: image,video
• --tool-choice <auto|required|none>
• --temperature <n>
• --max-output-tokens <n>
• --timeout <ms>
• --stream
• --output <path>
• --include-citations
• --job <path> (write a local job file while running)
• --slug <slug> (writes to jobs/<slug>.json when --job is omitted)

grokly chat

Multi‑turn conversation (stateful via previous_response_id).

Extra options:

• --previous <responseId>
• --session <path> (stores last response id)

grokly response <action> <id>

Fetch or delete a completed response by id.

Actions:

• get
• delete

grokly job <action> <path>

Check job status or print results from a local job file.

Actions:

• status
• result

Options:

• --render (render JSON output to text when stdout is a TTY)

grokly status

List local job files (defaults to ./jobs).

Options:

• --dir <path>
• --clean (delete job files older than --hours)
• --hours <n> (defaults to 24)
• --all (delete all job files)

grokly render <path>

Render JSON output (or raw response files) to text. When stdout is not a TTY, it prints JSON instead of rendering.

Configuration

Set the API key via environment or config:

export XAI_API_KEY="..."

Optional config file (loaded via lilconfig): grokly.config.json.

Search order (first match wins):

1. current working directory
2. ~/.config/grokly/

Config name:

• grokly.config.json

Example:

{
  "apiKey": "...",
  "model": "grok-4-1-fast-reasoning",
  "timeoutMs": 90000,
  "toolChoice": "auto",
  "tools": ["web", "x"],
  "allow": ["docs.noble.xyz", "@noble_xyz"],
  "capabilities": ["image"]
}

Tools

• --allow accepts domains and X handles.
  • Domains map to web_search.allowed_domains.
  • Handles map to x_search.allowed_x_handles.
• If --allow is set but --tools is not, the CLI auto‑enables the required tool(s).

Limits (xAI):

• Web allowlist: max 5 domains
• X allowlist: max 10 handles

Capabilities:

• image enables image understanding on web/x search tools.
• video enables video understanding only on x_search.

Tests

Integration tests call the xAI API directly. Set XAI_API_KEY (and optionally XAI_MODEL) before running:

export XAI_API_KEY="..."
export XAI_MODEL="grok-4-1-fast-reasoning"
pnpm test

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

License

MIT (inferred from existing tooling patterns).