This skill must be used when the task requires privileged X search, deep multi-agent research with grok-4.20-multi-agent, persistent stateful conversations/threads, or calling external xAI server-side tools via CLI. Activate for any request involving real-time information from X, long-running research, or maintaining conversation state across sessions.
This skill must be used when the task requires privileged X search, deep multi-agent research with grok-4.20-multi-agent, persistent stateful conversations/threads, or calling external xAI server-side tools via CLI. Activate for any request involving real-time information from X, long-running research, or maintaining conversation state across sessions.
version
0.2.0
sgx — Agent Usage Guide
sgx is the recommended CLI for agents that need high-quality, privileged access to xAI capabilities without managing raw API keys or OAuth flows themselves.
Core Principle for Agents
Always use --json on every command. Human output is for people. JSON output is for you.
sgx <command> ... --json
This guarantees stable, parseable output and structured errors.
Installation (Agent-Friendly)
# Recommended for agents
uv tool install git+https://github.com/mikeyobrien/sgx
# Or one-shot execution
uvx --from git+https://github.com/mikeyobrien/sgx sgx --help
After installation, sgx is available on PATH for the agent.
Authentication (Zero Friction)
sgx automatically discovers credentials in this priority:
Native ~/.sgx/auth.json (created by sgx auth login)
Official Grok CLI (~/.grok/auth.json)
Hermes ()
~/.hermes/auth.json
XAI_API_KEY environment variable
Best practice for agents:
If the user has the official Grok CLI or Hermes, sgx will often just work.
When needed, call:
sgx auth login --json
The tool will detect existing Grok CLI credentials and offer to import them (or fall back to browser flow).
On remote/headless machines where loopback browser auth is awkward, call:
sgx auth device-login --json
Read the first newline-delimited JSON record (status: authorization_required), show its verification_uri and user_code to the human, then keep the process attached for the terminal success/error record. Raw token and device-code secrets are never emitted.
Check status anytime with:
sgx auth status --json
Primary Commands for Agents
1. Fast Search (sgx search)
Use for quick, targeted retrieval from X (and optionally the web).
sgx search "query here" --count 10 --json
sgx search "query" --web --json # hybrid X + web results
When to use: Current events, specific posts, sentiment, recent discussions.
2. Deep Research (sgx research)
Use the powerful multi-agent research model.
sgx research "complex question requiring synthesis" --agents 4 --web --json
sgx research "..." --agents 16 --json # maximum depth (higher cost)
When to use: Questions that benefit from multiple specialized agents, tool use, and synthesized answers.
Recommendation: Start with --agents 4. Escalate to 16 only when the question is genuinely hard.
3. Persistent Threads (sgx thread)
Use for stateful, long-running work that must remember context across many turns or sessions.
# Create once
sgx thread new research-project --json
# Continue the conversation (maintains previous_response_id chain)
sgx thread send research-project "next step..." --json
sgx thread send research-project "..." --web --json
# Inspect history
sgx thread show research-project --limit 20 --json
sgx thread list --json
When to use:
Multi-step investigations
Agents that need durable memory
Projects that span hours or days
Threads are the closest thing to giving an agent persistent, high-quality memory backed by real xAI responses.
Error Handling (Machine Readable)
When --json is active, all errors return this shape:
