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
• 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

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).