grokly

name	grokly
description	Use the grokly CLI to query the xAI Responses API (single-turn, multi-turn, streaming, or job-file polling) with local project context when needed.

Grokly (CLI) — best use

Grokly is a lightweight CLI for xAI’s Responses API. Use it for single-turn prompts, stateful follow‑ups (via previous_response_id), streaming output, and local job files for manual polling. It intentionally avoids deprecated Chat Completions.

Golden path

1. Ensure XAI_API_KEY is set (never pass keys via flags).
2. Build the CLI if needed: pnpm build.
3. Use respond for one‑offs, chat for follow‑ups, and --stream for long responses.
4. Use --job <path> to write a local job file if you need polling.
5. Keep prompts precise; avoid sharing secrets in messages or files.

Commands (preferred)

• Single‑turn:

  • node dist/cli.js respond -m <model> -p "<prompt>"

• Multi‑turn (stateful):

  • node dist/cli.js chat -m <model> --session .grokly-session -p "<prompt>"
  • Follow‑up reuses the session file.

• Streaming:

  • node dist/cli.js respond -m <model> --stream -p "<prompt>"

• Local polling (job file):

  • node dist/cli.js respond -m <model> --job ./jobs/run1.json -p "<prompt>"
  • node dist/cli.js job status ./jobs/run1.json
  • node dist/cli.js job result ./jobs/run1.json

• Retrieve/delete by response id:

  • node dist/cli.js response get <responseId>
  • node dist/cli.js response delete <responseId>

Tools + allowlist

• Use --tools web,x,code to enable tools.
• Use --allow to restrict sources (domains for web, @handles for X).
• Limits (xAI): web allowlist max 5 domains; X allowlist max 10 handles.
• --capabilities image,video enables media understanding (video only works with x).

Configuration

Single config name: grokly.config.json. Search order:

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

Example:

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

Safety

• Never pass secrets via flags; use env/config.
• Don’t attach .env or credential files to prompts.
• Keep file scopes tight if you’re summarizing code or docs.

Notes

• Responses API supports stateful chat via previous_response_id but does not support server‑side polling.
• Job files are a local polling mechanism; they are not detached background jobs.