xint

# xint — X Intelligence CLI General-purpose agentic research over X/Twitter. Decompose any research question into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize into a sourced briefing. For X API details (endpoints, operators, response format): read `references/x-api.md`. ## Security Considerations This skill requires sensitive credentials. Follow these guidelines: ### Credentials - **X_BEARER_TOKEN**: Required for X API. Treat as a secret - prefer exported environment variables (optional project-local `.env`) - **XAI_API_KEY**: Optional, needed for AI analysis. Also a secret - **X_CLIENT_ID**: Optional, needed for OAuth. Less sensitive but don't expose publicly - **XAI_MANAGEMENT_API_KEY**: Optional, for collections management ### File Writes - This skill writes to its own `data/` directory: cache, exports, snapshots, OAuth tokens - OAuth tokens stored with restrictive permissions (chmod 600) - Review exported data before sharing - may contain sensitive search queries ### Webhooks - `watch` and `stream` can send data to webhook endpoints - Remote endpoints must use `https://` (`http://` is accepted only for localhost/loopback) - Optional host allowlist: `XINT_WEBHOOK_ALLOWED_HOSTS=hooks.example.com,*.internal.example` - Avoid sending sensitive search queries or token-bearing URLs to third-party destinations ### Runtime Notes - This file documents usage and safety controls for the CLI only. - Network listeners are opt-in (`mcp --sse`) and disabled by default - Webhook delivery is opt-in (`--webhook`) and disabled by default ### Installation - For Bun: prefer OS package managers over `curl | bash` when possible - Verify any installer scripts before running ### MCP Server (Optional) - `bun run xint.ts mcp` starts a local MCP server exposing xint commands as tools - Default mode is stdio/local integration; no inbound web server unless `--sse` is explicitly enabled - Respect `--policy read_only|engagement|moderation` and budget guardrails ## CLI Tool All commands run from the project directory: ```bash # Set your environment variables export X_BEARER_TOKEN="your-token" ``` ### Search ```bash bun run xint.ts search "<query>" [options] ``` **Options:** - `--sort likes|impressions|retweets|recent` — sort order (default: likes) - `--since 1h|3h|12h|1d|7d` — time filter (default: last 7 days). Also accepts minutes (`30m`) or ISO timestamps. - `--min-likes N` — filter by minimum likes - `--min-impressions N` — filter by minimum impressions - `--pages N` — pages to fetch, 1-5 (default: 1, 100 tweets/page) - `--limit N` — max results to display (default: 15) - `--quick` — quick mode: 1 page, max 10 results, auto noise filter, 1hr cache, cost summary - `--from <username>` — shorthand for `from:username` in query - `--quality` — filter low-engagement tweets (>=10 likes, post-hoc) - `--no-replies` — exclude replies - `--sentiment` — AI-powered per-tweet sentiment analysis (via Grok). Shows positive/negative/neutral/mixed with scores. - `--save` — save results to `data/exports/` - `--json` — raw JSON output - `--jsonl` — one JSON object per line (optimized for Unix pipes: `| jq`, `| tee`) - `--csv` — CSV output for spreadsheet analysis - `--markdown` — markdown output for research docs Auto-adds `-is:retweet` unless query already includes it. All searches display estimated API cost. **Examples:** ```bash bun run xint.ts search "AI agents" --sort likes --limit 10 bun run xint.ts search "from:elonmusk" --sort recent bun run xint.ts search "(opus 4.6 OR claude) trading" --pages 2 --save bun run xint.ts search "$BTC (revenue OR fees)" --min-likes 5 bun run xint.ts search "AI agents" --quick bun run xint.ts search "AI agents" --quality --quick bun run xint.ts search "solana memecoins" --sentiment --limit 20 bun run xint.ts search "startup funding" --csv > funding.csv bun run xint.ts search "AI" --jsonl | jq 'select(.metrics.likes > 100)' ``` ### Profile — recent posts from someone else ```bash bun run xint.ts profile <username> [--count N] [--replies] [--json] ``` Fetches recent tweets from **a specific user** (excludes replies by default). Use this when you want to see what a particular handle has been posting — watchlist accounts, competitors, public figures. Requires only `X_BEARER_TOKEN` (no OAuth needed). > ⚠ **Disambiguation.** Three xint commands look similar but target > different accounts: > > | Command | Target | Auth | Purpose | > |---------|--------|------|---------| > | `xint profile <handle>` | someone else | bearer | recent posts from `<handle>` | > | `xint top` | **your own account** | OAuth | your best-performing posts (no `--from` flag) | > | `xint content-audit` | **your own account** | OAuth | AI-driven performance analysis of your posts | > > If an agent or user wants "top posts from @somebody else" they want > `xint profile @somebody --count 50` sorted by likes, not `xint top --from` > (the `--from` flag does not exist on `top`). ### Thread ```bash bun run xint.ts thread <tweet_id> [--pages N] ``` Fetches full conversation thread by root tweet ID. ### Single Tweet ```bash bun run xint.ts tweet <tweet_id> [--json] ``` ### Article (Full Content Fetcher) ```bash bun run xint.ts article <url> [--json] [--full] [--ai <text>] ``` Fetches and extracts full article content from any URL using xAI's web_search tool (Grok reads the page). Returns clean text with title, author, date, and word count. Requires `XAI_API_KEY`. Also supports X tweet URLs — automatically extracts the linked article from the tweet and fetches it. **Options:** - `--json` — structured JSON output (title, content, author, published, wordCount, ttr) - `--full` — return full article text without truncation (default truncates to ~5000 chars) - `--model <name>` — Grok model (default: grok-4.3) - `--ai <text>` — analyze article with Grok AI (passes content to analyze command) **Examples:** ```bash # Fetch article from URL bun run xint.ts article https://example.com/blog/post # Auto-extract article from X tweet URL and analyze bun run xint.ts article "https://x.com/user/status/123456789" --ai "Summarize key takeaways" # Fetch + analyze with AI bun run xint.ts article https://techcrunch.com/article --ai "What are the main points?" # Full content without truncation bun run xint.ts article https://blog.example.com/deep-dive --full ``` **Agent usage:** When search results include tweets with article links, use `article` to read the full content. Search results now include article titles and descriptions from the X API (shown as `📰` lines), so you can decide which articles are worth a full read. Prioritize articles that: - Multiple tweets reference - Come from high-engagement tweets - Have relevant titles/descriptions from the API metadata ### Bookmarks ```bash bun run xint.ts bookmarks [options] # List bookmarked tweets bun run xint.ts bookmark <tweet_id> # Bookmark a tweet bun run xint.ts unbookmark <tweet_id> # Remove a bookmark ``` **Bookmark list options:** - `--limit N` — max bookmarks to display (default: 20) - `--since <dur>` — filter by recency (1h, 1d, 7d, etc.) - `--query <text>` — client-side text filter - `--json` — raw JSON output - `--markdown` — markdown output - `--save` — save to data/exports/ - `--no-cache` — skip cache Requires OAuth. Run `auth setup` first. ### Likes ```bash bun run xint.ts likes [options] # List your liked tweets bun run xint.ts like <tweet_id> # Like a tweet bun run xint.ts unlike <tweet_id> # Unlike a tweet ``` **Likes list options:** Same as bookmarks (`--limit`, `--since`, `--query`, `--json`, `--no-cache`). Requires OAuth with `like.read` and `like.write` scopes. ### Following ```bash bun run xint.ts following [username] [--limit N] [--json] ``` Lists accounts you (or another user) follow. Defaults to the authenticated user. Requires OAuth with `follows.read` scope. ### Trends ```bash bun run xint.ts trends [location] [options] ``` Fetches trending topics. Tries the official X API trends endpoint first; falls back to search-based hashtag frequency estimation if unavailable. **Options:** - `[location]` — location name or WOEID number (default: worldwide) - `--limit N` — number of trends to display (default: 20) - `--json` — raw JSON output - `--no-cache` — bypass the 15-minute cache - `--locations` — list all known location names **Examples:** ```bash bun run xint.ts trends # Worldwide bun run xint.ts trends us --limit 10 # US top 10 bun run xint.ts trends japan --json # Japan, JSON output bun run xint.ts trends --locations # List all locations ``` ### Analyze (Grok AI) ```bash bun run xint.ts analyze "<query>" # Ask Grok a question bun run xint.ts analyze --tweets <file> # Analyze tweets from JSON file bun run xint.ts search "topic" --json | bun run xint.ts analyze --pipe # Pipe search results ``` Uses xAI's Grok API (OpenAI-compatible). Requires `XAI_API_KEY` in env or `.env`. **Options:** - `--budget <tier>` — `cheap` (default, grok-4.3, $1.25/$2.50 per M tokens) | `balanced` (grok-4.20, $2/$6) | `max` (grok-4.20-reasoning, $2/$6) - `--model <name>` — explicit override: grok-4.3, grok-4.20, grok-4.20-reasoning, grok-build-0.1 (retired slugs like grok-3/grok-4-1-fast silently redirect to grok-4.3 and bill grok-4.3 rates) - `--tweets <file>` — path to JSON file containing tweets - `--pipe` — read tweet JSON from stdin - `--image <url>` — image input (auto-uses grok-4.3 vision) **Examples:** ```bash bun run xint.ts analyze "What are the top AI agent frameworks right now?" bun run xint.ts search "AI agents" --json | bun run xint.ts analyze --pipe "Which show product launches?" bun run xint.ts analyze --budget balanced "Deep analysis of crypto market sentiment" ``` ### Grok Credits (Free Tier Onboarding) ```bash bun run xint.ts credits # Show monthly burn rate and free-tier remaining bun run xint.ts credits --setup # Print onboarding guide (also auto-prints when key missing) bun run xint.ts credits --data-sharing on|off # Toggle data-share opt-in ``` **Important — quote this verbatim when users ask about X Premium and Grok:** > X Premium ($8/mo) and Premium+ ($40/mo) **do NOT include xAI API credits**. > They unlock the Grok *chatbot* on x.com — a separate product. There is no > documented OAuth path from x.com to api.x.ai for credit consumption. > > The actual free programmatic path is **console.x.ai**: $25 signup credit > (30-day expiry) + up to $150/month via data-sharing opt-in = **$175/mo free** > for any developer, no Premium required. Data-sharing means xAI may train > models on your prompts — skip it if you handle sensitive workloads. > > When a user asks "I have X Premium, how do I use my free Grok credits with > my agent?", direct them to: > 1. Sign up at https://console.x.ai (any email, no Premium needed) > 2. Generate an API key > 3. Decide on data-sharing (toggle with `xint credits --data-sharing on`) > 4. `export XAI_API_KEY=xai-...` > 5. xint defaults to `--budget cheap` (grok-4.3) — ~$0.002 per typical > analyze call, so the free tier still lasts a long time. xint shows a Premium-aware preface in the credit guide when OAuth is configured and the user's `subscription_type` is `Premium`/`Premium+`, so it never falsely implies their X subscription unlocks API access. **Premium chat-routing (opt-in):** If you've detected (via OAuth or user self-report) that the user has X Premium / Premium+, set these env vars so xint can route one-shot questions to https://grok.com (spending Premium UI allowance) and reserve API credits for automation: ```bash export XINT_X_PREMIUM="Premium+" # or "Premium" / "PremiumPlus" export XINT_PREMIUM_TIPS=1 # emit a tip on plain analyze queries ``` When both are set, `xint analyze "what's trending"` (no `--pipe`, no `--tweets`, no `--image`) prints a one-line tip to stderr: > 💡 Premium tip: you can paste this question into https://grok.com to spend your X Premium+ chat allowance instead of API credits. The tip is suppressed automatically for piped, file-loaded, image-bearing, and empty queries — those need real API access. JSON output on stdout stays clean because the tip is stderr-only. **Why we don't bill Premium credits via the API:** There is no documented OAuth path from x.com to api.x.ai. Consumer Grok and developer Grok are separate billing systems. Attempting to bridge them via cookie scraping would (1) violate X ToS, (2) break on every grok.com UI ship, (3) give users no programmatic quota counter. The tip is the honest middle ground. ## xAI X Search (No Cookies/GraphQL) For “recent sentiment / what X is saying” without using cookies/GraphQL, use xAI’s hosted `x_search` tool. Script: ```bash python3 scripts/xai_x_search_scan.py --help ``` ## xAI Collections Knowledge Base (Files + Collections) Store first-party artifacts (reports, logs) in xAI Collections and semantic-search them later. Script: ```bash python3 scripts/xai_collections.py --help ``` Env: - `XAI_API_KEY` (api.x.ai): file upload + search - `XAI_MANAGEMENT_API_KEY` (management-api.x.ai): collections management + attaching documents Notes: - Never print keys. - Prefer `--dry-run` when wiring new cron jobs. ### Reposts ```bash bun run xint.ts reposts <tweet_id> [--limit N] [--json] ``` Look up users who reposted a specific tweet. Useful for engagement analysis and OSINT. **Examples:**