Sgx

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:

1. Native ~/.sgx/auth.json (created by sgx auth login)
2. Official Grok CLI (~/.grok/auth.json)
3. Hermes (~/.hermes/auth.json)
4. 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:

{
  "status": "error",
  "error": "Human readable message",
  "type": "ExceptionClassName"
}

Always check "status" before trusting the payload.

Recommended Patterns for Agents

Pattern: Quick fact-finding

sgx search "<very specific query>" --count 5 --json

Pattern: Deep one-shot research

sgx research "<well-scoped question>" --agents 4 --web --json

Pattern: Long-running investigation

1. Create a dedicated thread once.
2. Send all subsequent work to that thread.
3. Periodically call thread show --json to review history.

Pattern: Hybrid Use search for raw data, feed interesting results into a research call or a thread for synthesis.

Capabilities Discovery

Agents can introspect available functionality with:

sgx --help
sgx <subcommand> --help

For structured discovery of commands, parse the Typer help or maintain a small static map of the public interface (search, research, thread*, auth*).

Summary — Agent Cheat Sheet

• Install once with uv tool install
• Authenticate with sgx auth login --json (usually automatic)
• Always pass --json
• Use search for speed, research for depth, thread for memory
• Errors are structured under --json
• Threads give you real persistent state without you managing previous_response_id

This skill exists so agents stop guessing how to use privileged xAI tools and instead call sgx correctly every time.